From 2b476c6bac155319cf5dc1623c33754483d8b47b Mon Sep 17 00:00:00 2001 From: Eric Pugh Date: Mon, 18 Nov 2024 11:24:46 -0500 Subject: [PATCH] Update docs to reflect that Opensearch is finicky about timezones --- docs/html/1.2.0/event.schema.html | 8 +++++--- docs/html/1.2.0/query.request.schema.html | 8 +++++--- docs/html/1.2.0/query.response.schema.html | 4 ++-- schema/1.2.0/event.schema.json | 4 ++-- schema/1.2.0/query.request.schema.json | 4 ++-- 5 files changed, 16 insertions(+), 12 deletions(-) diff --git a/docs/html/1.2.0/event.schema.html b/docs/html/1.2.0/event.schema.html index 48bd10b..b1fa8af 100644 --- a/docs/html/1.2.0/event.schema.html +++ b/docs/html/1.2.0/event.schema.html @@ -1,4 +1,4 @@ - Event tracking for UBI

Event tracking for UBI

Type: object

Version 1.2.0; last updated 2024-???. An event that occurred, typically in response to a user.

root application
Type: string

Name of the application that is integrated with UBI. You can think of application as in a source of search queries. For example, if you have a type ahead and a traditional search UI, then you might have type-ahead and primary-search as values.

Must be at most 100 characters long


Examples:

"type-ahead"
+ Event tracking for UBI 
   
 
 
Event tracking for UBI
Type: object
 
Version 1.2.0; last updated 2024-10-24. An event that occurred, typically in response to a user.
  
 
 
 
  
 
 
 
 
root    application
Type: string
 
Name of the application that is integrated with UBI. You can think of application as in a source of search queries. For example, if you have a type ahead and a traditional search UI, then you might have type-ahead and primary-search as values.
  
Must be at most 100 characters long
 
 
Examples:
 
"type-ahead"
 
 
"primary-search"
 
 
"amazon-shop"
 
 
"ABC-microservice"
@@ -10,7 +10,9 @@
 
 
"quepid-nightly-bot"
 
 
"BugsBunny::Firefox@0967084"
 
 
 
 
 
 
 
 
 
 
  
 
 
 
 
root    user_id
Type: string
 
The user ID associated with the person performing the interactions being logged on the site. Can be null/empty in case of an unauthenticated user.
  
Must be at most 100 characters long
 
 
Example:
 
"5e3b2a1c-8b7d-4f2e-a3d4-c9b2e1f3a4b5"
-
 
 
 
 
 
 
 
 
 
  
 
 
 
 
root    timestamp
Type: stringFormat: date-time
 
When the event took place. This timestamp is formatted according to the ISO 8601 standard.
  
 
Example:
 
"2018-11-13T20:20:39+00:00"
+
 
 
 
 
 
 
 
 
 
  
 
 
 
 
root    timestamp
Type: stringFormat: date-time
 
When the event took place. This timestamp is formatted according to the ISO 8601 standard. Please note that Opensearch requires a trailing Z or explicit timezone offset.
  
 
Examples:
 
"2018-11-13T20:20:39+00:00"
+
 
"2018-11-13T20:20:39Z"
+
 
"2018-11-13T20:20:39"
 
 
 
 
 
 
 
 
 
 
  
 
 
 
 
root    message_type
Type: string
 
Group various action_name's into logical bins.
  
Must be at most 100 characters long
 
 
Examples:
 
"QUERY"
 
 
"CONVERSION"
 
 
 
 
 
 
 
 
 
 
  
 
 
 
 
root    message
Type: string
 
Optional text message for the log entry. For example, for a message_type of QUERY, we would expect the text to be about what the user is searching on.
  
Must be at most 1024 characters long
 
 
 
 
 
 
 
 
  
 
 
 
 
root    event_attributes
Type: object
 
Extensible details about a specific event. A common example of an Additional Properties is the specific identifier of the user (user_id). Note: a user identifier is different then the required client_id attribute.
  
 
 
 
  
 
 
 
 
root    event_attributes    object
Type: object
 
Structure which contains identifying information of the object returned from the query that the user interacts with (i.e.: a book, a product, a post, etc..).
  
 
 
 
  
 
 
 
 
root    event_attributes    object    object_id

 
The id that a user could look up and find the object instance within the document corpus. Examples include: ssn, isbn, ean, etc. Variants need to be incorporated in the object_id, so for a t-shirt that is red, you would need SKU level as the object_id.
 
  
 
 
root    event_attributes    object    object_id    anyOf    item 0
Type: string
 
Must be at most 256 characters long
 
 
root    event_attributes    object    object_id    anyOf    item 1
Type: integer
 
 
 
Examples:
 
"XYZ-12345"
@@ -21,4 +23,4 @@
 
 
 
 
 
 
 
 
 
 
  
 
 
 
Additional Properties of any type are allowed.
 
root    event_attributes    object    additionalProperties
Type: object
 
 
 
 
 
 
 
 
 
 
 
 
  
 
 
 
 
root    event_attributes    position

 
Structure that contains information on the location of the event origin, such as screen x,y coordinates, or the nth object out of 10 results.
 
  
 
 
root    event_attributes    position    oneOf    item 0
Type: object
 
 
 
 
  
 
 
 
 
root    event_attributes    position    oneOf    item 0    ordinal
Type: object
 
The nth position of the document on the search results page.
  
 
 
 
  
 
 
 
 
root    event_attributes    position    oneOf    item 0    ordinal    index
Type: integer
 
The position of the document. For grid layout this would be left to right, ignoring wrapping.
  
 
Examples:
 
1
 
 
3
 
 
24
-
 
 
 
 
 
 
 
 
 
 
 
root    event_attributes    position    oneOf    item 1
Type: object
 
 
 
 
  
 
 
 
 
root    event_attributes    position    oneOf    item 1    xy
Type: object
 
The x,y coordinates on the screen for triggering an event.
  
 
 
 
  
 
 
 
 
root    event_attributes    position    oneOf    item 1    xy    x
Type: number
 
The horizontal location on the page or screen of the event.
  
 
 
 
 
 
 
 
  
 
 
 
 
root    event_attributes    position    oneOf    item 1    xy    y
Type: number
 
The vertical location on the page or screen of the event.
  
 
 
 
 
 
 
 
 
 
 
 
 
  
 
 
 
Additional Properties of any type are allowed.
 
root    event_attributes    position    additionalProperties
Type: object
 
 
 
 
 
 
 
 
 
 
 
 
  
 
 
 
Additional Properties of any type are allowed.
 
root    event_attributes    additionalProperties
Type: object
 
 
 
 
 
 
 
 
  
\ No newline at end of file
+
root event_attributes position oneOf item 1
Type: object

root event_attributes position oneOf item 1 xy
Type: object

The x,y coordinates on the screen for triggering an event.

root event_attributes position oneOf item 1 xy x
Type: number

The horizontal location on the page or screen of the event.

root event_attributes position oneOf item 1 xy y
Type: number

The vertical location on the page or screen of the event.

Additional Properties of any type are allowed.

root event_attributes position additionalProperties
Type: object

Additional Properties of any type are allowed.

root event_attributes additionalProperties
Type: object
\ No newline at end of file diff --git a/docs/html/1.2.0/query.request.schema.html b/docs/html/1.2.0/query.request.schema.html index 6084c4d..aa8693b 100644 --- a/docs/html/1.2.0/query.request.schema.html +++ b/docs/html/1.2.0/query.request.schema.html @@ -1,4 +1,4 @@ - Query Tracking for UBI

Query Tracking for UBI

Type: object

Version 1.2.0; last updated 2024-??. A query made by a user should include these attributes for UBI tracking.

root application
Type: string

Name of the application that is integrated with UBI. You can think of application as in a source of search queries. For example, if you have a type ahead and a traditional search UI, then you might have type-ahead and primary-search as values.

Must be at most 100 characters long


Examples:

"type-ahead"
+ Query Tracking for UBI 
   
 
 
Query Tracking for UBI
Type: object
 
Version 1.2.0; last updated 2024-10-24. A query made by a user should include these attributes for UBI tracking.
  
 
 
 
  
 
 
 
 
root    application
Type: string
 
Name of the application that is integrated with UBI. You can think of application as in a source of search queries. For example, if you have a type ahead and a traditional search UI, then you might have type-ahead and primary-search as values.
  
Must be at most 100 characters long
 
 
Examples:
 
"type-ahead"
 
 
"primary-search"
 
 
"amazon-shop"
 
 
"ABC-microservice"
@@ -8,5 +8,7 @@

root client_id
Type: string

The client issuing the query. This could be a unique browser, a microservice that performs searches, a crawling bot. If only authenticated users are tracked, then you could use a specific user id here, otherwise you should use something permanent and track user id as an Additional Property.

Must be at most 100 characters long


Examples:

"5e3b2a1c-8b7d-4f2e-a3d4-c9b2e1f3a4b5"
 
"quepid-nightly-bot"
 
"BugsBunny::Firefox@0967084"
-

root user_query
Type: string

The query as the user entered it. No length limit specified.

root query_attributes
Type: object

Any query modifiers like filter choices or pagination. Other attributes such as experiment identifiers that need to be tracked with the query.

Additional Properties of any type are allowed.

root query_attributes additionalProperties
Type: object

root object_id_field
Type: string

The name of the field that has the id of the objects that will be stored in the backend queries data store. So it you have a query for products and want to save the SKUs, then this might be sku and if you are querying for people, maybe this is ssn. If you do not provide this value then the default primary identifier in your search index will be used. For example _id on OpenSearch.

Must be at most 100 characters long

root timestamp
Type: stringFormat: date-time

When the query was issued. This timestamp is formatted according to the ISO 8601 standard. In many implementations of the UBI Query plugin the timestamp will be set for you at the time of the query being run. If you are replaying data, or want to track the timezone of the caller specifically, instead of using the search engine's timezone, then you will need to provide the timestamp instead.
Example:

"2018-11-13T20:20:39+00:00"
-
\ No newline at end of file +

root user_query
Type: string

The query as the user entered it. No length limit specified.

root query_attributes
Type: object

Any query modifiers like filter choices or pagination. Other attributes such as experiment identifiers that need to be tracked with the query.

Additional Properties of any type are allowed.

root query_attributes additionalProperties
Type: object

root object_id_field
Type: string

The name of the field that has the id of the objects that will be stored in the backend queries data store. So it you have a query for products and want to save the SKUs, then this might be sku and if you are querying for people, maybe this is ssn. If you do not provide this value then the default primary identifier in your search index will be used. For example _id on OpenSearch.

Must be at most 100 characters long

root timestamp
Type: stringFormat: date-time

When the query was issued. This timestamp is formatted according to the ISO 8601 standard. In many implementations of the UBI Query plugin the timestamp will be set for you at the time of the query being run. If you are replaying data, or want to track the timezone of the caller specifically, instead of using the search engine's timezone, then you will need to provide the timestamp instead. Please note that Opensearch requires a trailing Z or explicit timezone offset.
Examples:

"2018-11-13T20:20:39+00:00"
+
"2018-11-13T20:20:39Z"
+
"2018-11-13T20:20:39"
+
\ No newline at end of file diff --git a/docs/html/1.2.0/query.response.schema.html b/docs/html/1.2.0/query.response.schema.html index 11ce200..fbb0e43 100644 --- a/docs/html/1.2.0/query.response.schema.html +++ b/docs/html/1.2.0/query.response.schema.html @@ -1,3 +1,3 @@ - Query Response When Using UBI

Query Response When Using UBI

Type: object

Version 1.2.0; last updated 2024-??. The response to a query made by a user should support this schema.

root query_id

The unique identifier of a query, typically a UUID, but can be any string.

root query_id oneOf item 0
Type: stringFormat: uuid

Example:

"00112233-4455-6677-8899-aabbccddeeff"
+ Query Response When Using UBI 
   
 
 
Query Response When Using UBI
Type: object
 
Version 1.2.0; last updated 2024-10-24. The response to a query made by a user should support this schema.
  
 
 
 
  
 
 
 
 
root    query_id

 
The unique identifier of a query, typically a UUID, but can be any string.
 
  
 
 
root    query_id    oneOf    item 0
Type: stringFormat: uuid
 
 
Example:
 
"00112233-4455-6677-8899-aabbccddeeff"
 
 
 
 
root    query_id    oneOf    item 1
Type: string
 
Must be at most 100 characters long
 
 
Example:
 
"1234-user-5678"
-
 
 
 
 
 
 
  
\ No newline at end of file
+
\ No newline at end of file diff --git a/schema/1.2.0/event.schema.json b/schema/1.2.0/event.schema.json index 24439fe..65f2aeb 100644 --- a/schema/1.2.0/event.schema.json +++ b/schema/1.2.0/event.schema.json @@ -66,10 +66,10 @@ "examples": ["5e3b2a1c-8b7d-4f2e-a3d4-c9b2e1f3a4b5"] }, "timestamp": { - "description": "When the event took place. This timestamp is formatted according to the ISO 8601 standard.", + "description": "When the event took place. This timestamp is formatted according to the ISO 8601 standard. _Please note that Opensearch requires a trailing `Z` or explicit timezone offset._", "type": "string", "format": "date-time", - "examples": ["2018-11-13T20:20:39+00:00"] + "examples": ["2018-11-13T20:20:39+00:00", "2018-11-13T20:20:39Z", "2018-11-13T20:20:39"] }, "message_type": { "description": "Group various `action_name`'s into logical bins.", diff --git a/schema/1.2.0/query.request.schema.json b/schema/1.2.0/query.request.schema.json index f26abe9..a19d309 100644 --- a/schema/1.2.0/query.request.schema.json +++ b/schema/1.2.0/query.request.schema.json @@ -55,10 +55,10 @@ "maxLength": 100 }, "timestamp": { - "description": "When the query was issued. This timestamp is formatted according to the ISO 8601 standard. In many implementations of the UBI Query plugin the timestamp will be set for you at the time of the query being run. If you are replaying data, or want to track the timezone of the caller specifically, instead of using the search engine's timezone, then you will need to provide the timestamp instead.", + "description": "When the query was issued. This timestamp is formatted according to the ISO 8601 standard. In many implementations of the UBI Query plugin the timestamp will be set for you at the time of the query being run. If you are replaying data, or want to track the timezone of the caller specifically, instead of using the search engine's timezone, then you will need to provide the timestamp instead. _Please note that Opensearch requires a trailing `Z` or explicit timezone offset._", "type": "string", "format": "date-time", - "examples": ["2018-11-13T20:20:39+00:00"] + "examples": ["2018-11-13T20:20:39+00:00", "2018-11-13T20:20:39Z", "2018-11-13T20:20:39"] } } }