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 will return below:

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

string query

[Optional] Parameter representing the search criteria. If unspecified, returns all values. Can be used with skip, count and orderby.

int skip

[Optional] Parameter representing the zero-based offset of the first SdsStream to retrieve. The number of matched items to skip over before returning. If unspecified, a default value of 0 is used. Use when more items match the search criteria than can be returned in a single call.

int count

[Optional] Parameter representing the maximum number of streams to retrieve. If unspecified, a default value of 100 is used.

string orderby

[Optional] Parameter representing the sorted order in which streams are returned. Requires a field name (orderby=name, for example). Default order is ascending (asc). Add desc for descending order (orderby=name desc, for example). If unspecified, there is no sorting of results.

.NET client libraries methods

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

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

If skip is set to 100, the following call will return 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 Streams.

Searchable Properties

Searchable Child Resources

Note: 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. See Search in SDS for more information.

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

string query

[Optional] Parameter representing the search criteria. If unspecified, returns all values. Can be used with skip, count and orderby.

int skip

[Optional] Parameter representing the zero-based offset of the first SdsStream to retrieve. If unspecified, a default value of 0 is used. Use when more items match the search criteria than can be returned in a single call.

int count

[Optional] Parameter representing the maximum number of streams to retrieve. If unspecified, a default value of 100 is used.

.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 on the [Streams](xref:eam metadata has unique syntax rules. For details, 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 Types.

Searchable Properties

Note: The 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 will return 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

string query

[Optional] Parameter representing the search criteria. If unspecified, returns all values. Can be used with skip, count and orderby.

int skip

[Optional] Parameter representing the zero-based offset of the first type to retrieve. If unspecified, a default value of 0 is used. Use when more items match the search criteria than can be returned in a single call.

int count

[Optional] Parameter representing the maximum number of types to retrieve. If unspecified, a default value of 100 is used.

.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

Note: 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 are also searched. See the following example.

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

string query

[Optional] Parameter representing the search criteria. If unspecified, returns all values. Can be used with skip, count and orderby.

int skip

[Optional] Parameter representing the zero-based offset of the first stream view to retrieve.If unspecified, a default value of 0 is used. Use when more items match the search criteria than can be returned in a single call.

int count

[Optional] Parameter representing the maximum number of stream views to retrieve. If unspecified, a default value of 100 is used.

.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 a space or one or more punctuation characters, such as *, !, ?, ., and a space. A query string followed without space 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 they are at the beginning and end, for example *Tank*, but not *Ta*nk, Ta*nk*, or *Ta*nk*.

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 will not be matched unless wildcards are used. For example, if you are searching for a stream with description Pump three on unit five, a query "unit five" will not match the description, but *"unit five" will.

Note that while wildcard (*) can be used either in 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 will only match 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

Streams 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 both in metadata keys and values with one caveat: wildcard (*) used in the field (left of field-scoped operator (:)) will only search 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.