Chapter 46 Querying Data

TopicQueries allow a DataReader to query the sample cache of its matching DataWriters. You can create a TopicQuery with the DataReader's create_topic_query() API. When a DataReader creates a TopicQuery, DDS will propagate TopicQueries to other DomainParticipants and their DataWriters. When a DataWriter matching with the DataReader that created the TopicQuery receives it, it will send the cached samples that pass the TopicQuery's filter.

Note: Do not confuse TopicQueries with QueryContitions (see18.9.7 ReadConditions and QueryConditions). QueryConditions filter data samples on a DataReader cache based on its content and state. In contrast, TopicQueries request specific data samples from a DataWriter's cache based on filter criteria. These requests allow a DataReader to retrieve data that it may not have received through standard subscription mechanisms.

Only samples that fall within the writer_depth (in the 59.9 DURABILITY QosPolicy) for an instance are evaluated against the TopicQuery filter. While the DataWriter is waiting for acknowledgements from one or more DataReaders, there may temporarily be more than writer_depth samples per instance in the DataWriter's queue if the 59.12 HISTORY QosPolicy depth is set to a higher value than writer_depth. Those additional samples past writer_depth are not eligible to be sent in response to the TopicQuery.

To enable and configure TopicQueries, use the following QoS policies:

• In the DataWriter's 59.24 TOPIC_QUERY_DISPATCH_QosPolicy (DDS Extension), set enable to TRUE (by default, it is FALSE). A DataWriter ignores TopicQueries unless they are explicitly enabled using this policy.
• disable_topic_query_publication (in the 58.1 ASYNCHRONOUS_PUBLISHER QosPolicy (DDS Extension)) must also be left to its default value, FALSE, and enabled_builtin_channels (in the 56.3 DISCOVERY_CONFIG QosPolicy (DDS Extension)) must not disable the service request channel (it is enabled by default).

The delivery of TopicQuery samples occurs in a separate RTPS channel to allow DataReaders to receive TopicQuery samples and live samples in parallel. This is a key difference with respect to the 59.9 DURABILITY QosPolicy, with which new non-volatile DataReaders first receive all historical data before they start receiving live data.

Late-joining DataWriters will also discover existing TopicQueries. To delete a TopicQuery you must use the DataReader's delete_topic_query().

After deleting a TopicQuery, new DataWriters will not discover it and existing DataWriters currently publishing cached samples may stop before delivering all of them.

By default, a TopicQuery queries the samples that were in the DataWriter's queue at the time the DataWriter received the TopicQuery. These TopicQueries are snapshot TopicQueries. However, a TopicQuery can be created in “continuous” mode; in this case, a DataWriter will continue delivering samples that pass a continuous TopicQuery filter until the DataReader application explicitly deletes it. These TopicQueries are continuous TopicQueries.

The samples received in response to a TopicQuery are stored in the associated DataReader's cache. Any of the read/take operations can retrieve TopicQuery samples. The field DDS_SampleInfo::topic_query_guid associates each sample with its TopicQuery. If the read sample is not in response to a TopicQuery, this field will be DDS_GUID_UNKNOWN.

You can choose to read or take only TopicQuery samples, only live samples, or both. To support this, ReadConditions and QueryConditions provide the DataReader's create_querycondition_w_params() and create_readcondition_w_params() APIs.

Each TopicQuery is identified by a GUID that can be accessed using the TopicQuery's get_guid() method.