URL Query Parameters¶

Overview¶

URL Query Parameters provide a convenient way to customize and share data with your applications. By leveraging these parameters, you can control time ranges, apply filters, and configure various settings for Dashboards, Datasets, Resource Instances, and Worksheets. This flexibility allows for seamless integration and enhanced data exploration within the Observe platform.

Example Format¶

https://${Customer_ID}.observeinc.com/workspace/12345678/resource/41950995~tinyk8s-ops~uid~575ffab0-1850-4505-b41d-bee84b3b310c?time-end=1683575622716&time-start=1683561222716

For example, the URL "https://${Customer_ID}.observeinc.com/workspace/12345678/dataset/event/Device-Events-98765432?s=2713-yc1s7omo" links to a Dataset in your instance. If you want to add a filter parameter with key “fig” and the value “bar” with the operator “=” to the URL, use the parameter, ?filter-fig=bar.

You can add links in your application to your Observe instance. For instance, you may want to link to a Dashboard that you access frequently without logging into Observe and locating it. Your link HTML code may look something like the following:

<html>
<p>
<a href="https://123456789012.observeinc.com/workspace/41000009/dataset/event/Container-Logs-41007104?filter-status=error">Container Logs Dataset with Filter Status = Error</a>
</p>
</html>

Note

Observe recommends to URI-Component encode all URL parameter keys and values when creating a URL string. Some browsers accept unencoded URLs, but this behavior may be unreliable. For best results, URI-encode query string parameter keys and values.

Observe generates URLs with parameters matching your current view in Observe. URLs generated by Observe contain proper URI encoding in them.

The following tables list the currently supported URL Parameters:

Time Ranges¶

Parameter	Description
`"time-start": "2023-03-08T16%3A54%3A05.268Z",`	Accepts a timestamp or an ISO time.
`"time-end": "2023-03-08T16%3A54%3A05.268Z",`	Accepts a timestamp or an ISO time.
`"time-preset": "preset_key",`	Accepts a preset key.

Example Date and Time Formats

Formats	Description
`?time-start=1686165391864`	UNIX timestamp in milliseconds
`?time-start=2023-06-07T15:02:31-04:00`	An ISO string with a timezone offset specified
`?time-start=2023-06-07T15:08:07Z`	An ISO string specified in UTC time
`?time-start=2023-06-07T15.02.31-04.00`	A custom ISO format for URL readability

Note

When passing an ISO string containing precision to seconds, not milliseconds, you may replace the : with . in the URL for an easier-to-read format. The . does not have to be URI encoded.

The time-preset parameter supports the following preset keys:

TODAY
YESTERDAY
THIS_DAY_LAST_WEEK
LAST_WEEK
LAST_MONTH
PAST_5_MINUTES
PAST_10_MINUTES
PAST_15_MINUTES
PAST_30_MINUTES
PAST_60_MINUTES
PAST_2_HOURS
PAST_4_HOURS
PAST_24_HOURS
PAST_7_DAYS
PAST_30_DAYS

Filters for Dataset Pages¶

For Event and Resource Datasets, you can control filters for these pages using URL parameters. You can enter duplicate filters for multiple values. For example, ?filter-status=error&filter-status=warning produces 2 filters for the status column in the dataset.

For simplicity and readability, when using the operator = (Equals) you may use the “short-hand” parameter specification, filter-<key>=value. Otherwise, you must specify the full filter syntax delimited by a | character, such as filter=key|!=|value.

If you omit the value, Observe assumes an empty string. To specify the value as null, you need to prefix your URL parameter with null-. For the shorthand version, this becomes null-filter-<key>, and for the long form, it becomes null-filter=key|!= for key != null.

Parameter	Value	Description
`filter-<columnId>`	Value	`columnId = value`
`filter`	`columnId\|operator\|value`	`columnId operator value`
`null-filter-<columnId>`		`columnId = null`
`null-filter`	`columnId\|operator`	`columnId operator`

Use the following operators for non-shorthand syntax:

Operator	Description
`=`	Equal
`!=`	Not Equal
`>`	Greater than
`<`	Less than
`>=`	Greater than or Equal to
`<=`	Less than or Equal to
`~`	Contains
`!~`	Does Not Contain

Filters for Filtered Datasets in Dashboards¶

Filterable Datasets allow you to customize Dashboard views using Dataset filters. URL Parameters for these closely resemble URL parameters for regular dataset filters. Instead of using filter, you can use filterds-<datasetId> to target a filterable dataset on a Dashboard.

Parameter	Value	Description
`filterds-<datasetid>-<columnId>`	Value	is equal to `value`. Allows you to specify the `columnId` in the parameter name.
`filterds-<datasetid>`	`columnId\|operator\|value`	`columnId` operator value
`null-filterds-<datasetid>-<columnId>`		`columnId = null`
`null-filterds-<datasetid>`	`columnId\|operator`	`columnId operator null`

Parameters for Dashboards and Worksheets¶

You can also configure parameters for Dashboards and Worksheets using URL parameters. The author of the dashboard configures these parameters and may have one of the following types:

Text
Dropdown
Number
Resource Instance

Text, dropdown, and number values pass as written. For Resource instances, the URL accepts a custom serialization format.

Parameter	Value	Description
`param-<key>`	`a value`	One or more global search strings (multiple strings may be passed, for example, `search=log&search=error`
`param-<key>`	`resourceLabel~primaryKeyName~primaryKeyValue`	Sets the value of a resource instance parameter to the following Resource ID: `{ label: resourceLabel, primaryKeys: [{ name: "primaryKeyName", value: "primaryKeyValue"}] }`

For example, use ?param-stringParam=value for a simple parameter, and ?param-key=DiskPressure-ip-172-31-46-130-b3487a97-46d6-45c8-8b98-f67669391713~clusterUid~b3487a97-46d6-45c8-8b98-f67669391713~name~ip-172-31-46-130~type~DiskPressure for a resource parameter.

Resource Parameter Serialization Rules¶

If you open a Resource Instance, you see in the URL resource/<datasetId>~<label>~<...primaryKeyValues> where ...primaryKeyValues is an enumeration for every key~value in the primaryKeys list for the resource. The order of the key/value pairs is not important.
You can use <label>~<...primaryKeyValues> as a value for a Resource Instance parameter. You should not specify the Dataset ID as the parameter defines it.
You may omit the label, but you must pass ~ as your first character in the sequence because you have omitted the label. For example, ?~<...primaryKeyValues>~ would be the correct syntax in this case.
You must escape ~ and \ in labels and primary keys with \(backslash).
- Because of the nature of this custom serialization format, labels and primary key names or values that contain the character ~ or \ must be encoded by prefixing with \. For example, if you have a label such as Some~label, this must be passed as Some\~label so that it does not split incorrectly during deserialization. Similarly, if you have a label such as Some\label, this must be passed as Some\\label as \ is an escape character in this serialization format, so must be un-escaped to be parsed correctly. The same escaping needs to be applied to the names and values of the primary keys, as well.

The Explore Page with Filter and Search¶

On the Explore page, you can also control the Filter and Search settings of the Filter bar at the top of the page.

Parameter	Value	Description
`search`	`string`	Sets the value of the parameter with ID “key” to “a value”
`exclude`	`string`	Similar to `search`, but instead of including results that contain the string, it excludes results that contain the string.
`filter`	Encoded JSON `string`	The URL differs slightly from using filters on other pages. It requires `columnID operator value` and expresses this using a JSON string which must be encoded before passing it. For example, name = “AWS 3” translates to `{"name":{"=":["AWS 3]}}` -> `%7B"name"%3A%7B"%3D"%3A%5B"AWS%203"%5D%7D%7D`.

Filters and Apps¶

On the Apps page, you may control a single search for the table using the search parameter.

Parameter	Value	Description
`search`	`string`	One `search` string can be passed.

View State¶

Parameter	Description
`"v-dash": "id",`	selected dashboard (Dataset and Resource Instance Pages)
`"v-tab": "tab",`	selected tab (Dataset and Resource Instance Pages)