Edit this page

The search protocol lets you query across all digital twins using a reactive-streams-based flow of paginated results.

TL;DR: Send a subscribe command to start a search, then use request to pull pages of results and cancel to stop early. Ditto responds with created, next, complete, or failed events.

Overview

The search aspect of the Ditto Protocol consists of 3 commands and 4 events that implement the reactive-streams protocol over any duplex transport layer. Ditto acts as the publisher of search result pages, and you act as the subscriber.

You control how fast pages arrive and can cancel a search before all results are sent.

Connections support

While connections do not inherently expose a duplex transport layer, the search protocol works with them too. Send commands via any connection source, and receive events at the source’s reply-target.

How it works

Signal mapping

Each search command or event corresponds to a reactive-streams signal. A subscription ID links all messages of one search query.

Reactive-streams signal Search protocol topic Type Direction
Publisher#subscribe _/_/things/twin/search/subscribe Command Client to Ditto
Subscription#request _/_/things/twin/search/request Command Client to Ditto
Subscription#cancel _/_/things/twin/search/cancel Command Client to Ditto
Subscriber#onSubscribe _/_/things/twin/search/created Event Ditto to Client
Subscriber#onNext _/_/things/twin/search/next Event Ditto to Client
Subscriber#onComplete _/_/things/twin/search/complete Event Ditto to Client
Subscriber#onError _/_/things/twin/search/failed Event Ditto to Client

Interaction pattern

Client sends (in order):

subscribe request* cancel?

Ditto responds with:

created next* (complete | failed)?
  1. You send a subscribe command. Ditto always responds with a created event containing the subscription ID.
  2. You send request commands to pull pages. Ditto sends next events with results.
  3. When all results are delivered, Ditto sends complete. On error, Ditto sends failed.
  4. You can send cancel at any time to stop receiving results.

Ditto guarantees that no complete or failed event arrives before your first request command. This simplifies concurrency handling on multi-threaded clients.

After sending cancel, you may still receive buffered next, complete, or failed events.

Commands (client to Ditto)

Subscribe

Start a new search. Ditto always responds with a created event.

Field Value
topic _/_/things/twin/search/subscribe
path /
fields Optional comma-separated list of Thing fields to include in results.
value JSON object specifying the query.
   

You specify the filter, options, and namespaces in the value field. They have the same semantics and defaults as other search APIs:

  • size(<count>) in options limits results per next event (default: 25, max: 200).
  • sort(<+|-><property>, ...) in options sets result order (default: sort(+thingId)).

The cursor and limit paging options from the HTTP API are not supported here – the search protocol handles pagination automatically through the reactive-streams flow.

Request

After receiving a subscription ID from the created event, send request commands to tell Ditto how many pages you are ready to receive.

Field Value
topic _/_/things/twin/search/request
path /
value JSON object specifying the page count.
   

Cancel

Send a cancel command to stop receiving results. Pages already in flight may still arrive, but Ditto eventually stops sending events for this subscription.

Field Value
topic _/_/things/twin/search/cancel
path /
value JSON object identifying the subscription.
   

Events (Ditto to client)

Created

Ditto sends a created event in response to every subscribe command. It contains the subscription ID you need for subsequent commands.

Field Value
topic _/_/things/twin/search/created
path /
value JSON object with the subscription ID.
   

Next

Each next event contains one page of search results. Ditto sends at most as many pages as you requested via request commands.

Field Value
topic _/_/things/twin/search/next
path /
value JSON object with one page of results.
   

Complete

Ditto sends complete when all search results have been delivered.

Field Value
topic _/_/things/twin/search/complete
path /
value JSON object identifying the subscription.
   

Failed

Ditto sends failed when an internal error occurs or when you breach the reactive-streams specification. You cannot request more results after a failed event.

Field Value
topic _/_/things/twin/search/failed
path /
value JSON object with the failure reason.
   

Further reading

Tags: protocol search