Search in SDS

You can search for objects using texts, phrases, and fields in Sequential Data Store (SDS). The REST APIs (or .NET client libraries methods GetStreamsAsync, GetTypesAsync, and GetStreamViewsAsync) return items that match the search criteria within a given namespace. By default, the query parameter applies to all searchable object fields.

For example, a namespace contains the following streams:

A GetStreamsAsync call with different queries returns:

Requests

GET api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Streams?query=name:pump name:pressure&orderby=name

GET api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Streams?query=name:pump name:pressure&orderby=id asc

GET api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Streams?query=name:pump name:pressure&orderby=name desc

GET api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Streams?query=name:pump name:pressure&orderby=name desc&skip=10&count=20

Parameters

.NET client libraries methods

If there are 175 streams that match the search criteria "temperature" in a single call for example, the following call returns the first 100 matches:

_metadataService.GetStreamsAsync(query:"temperature", skip:0, count:100)

If skip is set to 100, the following call returns the remaining 75 matches while skipping over the first 100:

_metadataService.GetStreamsAsync(query:"temperature", skip:100, count:100)

Search for streams

Streams search is exposed through the REST API and the client libraries method GetStreamsAsync.

For more information on stream properties, see Stream properties.

Searchable properties

Searchable child resources

¹:You can access stream metadata and tags through Metadata API and Tags API respectively. Metadata and tags are associated with streams and can be used as search criteria. For more information, see How search works with stream metadata.

Request

Search for streams using the REST API and specifying the optional query parameter:

GET api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Streams?query={query}&skip={skip}&count={count}

Parameters

.NET client libraries method

GetStreamsAsync is used to search for and return streams.

_metadataService.GetStreamsAsync(query:"QueryString", skip:0, count:100);

The stream fields valid for search are identified in the fields table located in Stream properties. Note that stream metadata has unique syntax rules. See How search works with stream metadata.

Search for types

Type search is exposed through the REST API and the client libraries method GetTypesAsync. For more information on type properties, see SdsType fields and properties.

Searchable properties

¹:Name and Id of an SdsType are included in its Properties field. Similarly, Name and Id of a nested type are included in its Properties. If there are two types with the same Properties, Name or Id, the search returns both types in the result.

Request

Search for types using the REST API and specifying the optional query parameter:

GET api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Types?query={query}&skip={skip}&count={count}

Parameters

.NET client libraries method

GetTypesAsync is used to search for and return types.

_metadataService.GetTypesAsync(query:"QueryString", skip:0, count:100);

Search for stream views

Stream view search is exposed through the REST API and the client libraries method GetStreamViewsAsync. For more information on stream view properties, see Stream views.

Searchable properties

¹The Properties collection contains a list of SdsStreamViewProperty objects. The query attempts to find a match on the SdsStreamViewProperty's Id, SourceTypeId, and TargetTypeId fields. The Properties collection of nested views is also searched. See the example below.

Example

You can search for ComplexView using the Id("NestedView"), SourceTypeId, and TargetTypeId of NestedView, but not its Description ("An example of a nested view").

{
  "Id": "ComplexView",
  "Name": "ComplexView",
  "SourceTypeId": "ComplexSourceType",
  "TargetTypeId": "ComplexTargetType",
  "Description": null,
  "Properties": [
    {
      "SourceId": "Value",
      "TargetId": "Value",
      "SdsStreamView": {
        "Id": "NestedView",
        "SourceTypeId": "NestedType",
        "TargetTypeId": "NestedType",
        "Description": "An example of a nested view",
        "Properties": [
          {
            "SourceId": "Value",
            "TargetId": "Value"
          }
        ]
      }
    }
  ]
}

Request

Search for stream views using the REST API and specifying the optional query parameter:

GET api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/StreamViews?query={query}&skip={skip}&count={count}

Parameters

.NET client libraries method

GetStreamViewsAsync is used to search for and return stream views.

_metadataService.GetStreamViewsAsync(query:"QueryString", skip:0, count:100);

Tokenization

Tokenization is the process of breaking a string sequence into pieces called tokens using specific characters to delimit tokens. User-specified queries are tokenized into search terms. How the query string is tokenized can affect search results.

Delimit the terms with either:

1. A space.

2. One or more punctuation characters (*, !, ?, ., for example) and a space. Any query string followed without a space or by other punctuation characters does not trigger tokenization and is treated as part of the term.

If your query has a wildcard (*) operator after a punctuation character, neither the punctuation nor the wildcard operator is tokenized. To specifically search for a term that has trailing punctuation, enclose the query in quotation marks to ensure that the punctuation is part of the query. See examples below:

Search operators

You can use search operators in the query string to get more refined search results. Use operators AND,OR, and NOT in all caps.

Examples

Field-scoping (:) operator

You can qualify the search to a specific field using the : operator.

fieldname:fieldvalue

Request

GET api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Streams?query=name:pump name:pressure

.NET client libraries method

GetStreamsAsync(query:"name:pump name:pressure");

Wildcard (*) operator

You can use the wildcard operator (*) to complement an incomplete string. It can only be used once per token, unless there is one at the beginning and another at the end (*Tank* but not *Ta*nk, Ta*nk*, or *Ta*nk*, for example).

Request

GET api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Streams?query=log*

.NET client libraries method

GetStreamsAsync(query:"log*");

Double quotes ("") operator

Tokenized search terms are delimited by whitespace and punctuation. To include these delimiters in a search, enclose them in double quotes.

When using double quotes, the matching string must include the whole value of the field on the object being searched. Partial strings are not matched unless wildcards are used. For example, if you are searching for a stream with the description Pump three on unit five, a query "unit five" will not match the description, but *"unit five" will.

Note that while you can use a wildcard (*) either inside or outside of quotes, it is treated as a string literal inside quotes. For example, you can search for "dog food"* to find a string that starts with "dog food", but if you search for "dog food*", it only matches the value of "dog food*".

Request

GET api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Streams?query="pump pressure"

.NET client libraries method

GetStreamsAsync(query:"\\"pump pressure\\"");

How search works with stream metadata

Stream metadata behaves differently with search syntax rules described in the previous sections.

A namespace with streams with respective metadata key-value pairs

Field-scoping (:) Operator

Stream metadata key is only searchable in association with its value. This pairing is defined using the field-scoping (:) operator.

myStreamMetadataKey:myStreamMetadataValue

Metadata key is not searched if the operator (:) is missing in the query string. The search is then limited to metadata values along with other searchable fields in the stream.

Request

GET api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Streams?query=manufacturer:company

.NET client libraries method

GetStreamsAsync(query:"manufacturer:company");

Wildcard (*) Operator

Wildcard (*) character can be used in both metadata keys and values with one caveat: a wildcard (*) used in the field (left of field-scoped operator (:)) only searches within SdsStream metadata.

Request

GET api/v1/Tenants/{tenantId}/Namespaces/{namespaceId}/Streams?query=manufa*turer:compan*

.NET client libraries method

GetStreamsAsync(query:"manufa*turer:compan*");

Special characters in search queries

Add the backslash escape character ( \ ) before any special characters in search queries. The following special characters require an escape character:

" | / \* \ ( ) :

The following are examples of using the escape character in query strings.