Filter Use Cases

Working with data filters.

Working with data filters.

Introduction <br>

RTI Connext supports filtering data either during the exchange from dds::pub::DataWriter to dds::sub::DataReader, or after the data has been stored at the dds::sub::DataReader.

Filtering during the exchange process is performed by a dds::topic::ContentFilteredTopic, which is created by the dds::sub::DataReader as a way of specifying a subset of the data samples that it wishes to receive.

Filtering samples that have already been received by the dds::sub::DataReader is performed by creating a dds::sub::cond::QueryCondition, which can then used to check for matching samples, be alerted when matching samples arrive, or retrieve matching samples.

Filtering may be performed on any topic, either keyed or un-keyed, except the built-in topics. Filtering may be performed on any field, subset of fields, or combination of fields, subject only to the limitations of the filter syntax.

Code Examples

The following #includes are needed for the examples on this page

#include <iostream>
#include <dds/topic/ddstopic.hpp>
#include <dds/sub/ddssub.hpp>
#include "Foo.hpp"

Filtering with ContentFilteredTopic

• Set up a Subscriber
• Set up a Topic
• Create a ContentFilteredTopic, of user data type Foo:

      // Create the DomainParticipant
      dds::domain::DomainParticipant participant(0);
   
      // Create a Topic
      dds::topic::Topic<Foo> topic(participant, "MyTopicName");
   
      // Create the parameter list
      std::vector<std::string> cft_parameters(2);
      cft_parameters[0] = "1";
      cft_parameters[1] = "100";
   
      // Create the ContentFilteredTopic
      dds::topic::ContentFilteredTopic<Foo> cft(
          topic, // related topic
          "ContentFilteredTopic", // local name for the CFT
          dds::topic::Filter( // filter (constructed in-line in this example)
              "x > %0 AND x < %1", // expression
              cft_parameters)); // parameter vector
   
      // Parameters are optional
      dds::topic::ContentFilteredTopic<Foo> cft2(
          topic,
          "ContentFilteredTopic2",
          dds::topic::Filter("x = 100 AND y < 20"));

  
  
• Create a DataReader using the ContentFilteredTopic:

      dds::sub::DataReader<Foo> reader(subscriber, cft);

  Once setup, reading samples with a dds::topic::ContentFilteredTopic is exactly the same as normal reads or takes, as described in DataReader Use Cases.
  
  
• Changing filter criteria:

      std::vector<std::string> new_cft_parameters(2);
      new_cft_parameters[0] = "5";
      new_cft_parameters[1] = "9";
   
      cft.filter_parameters(new_cft_parameters.begin(), new_cft_parameters.end());

Filtering with Query Conditions

• Creating a QueryCondition

      // Create parameter list
      std::vector<std::string> query_parameters(2);
      query_parameters[0] = "1";
      query_parameters[1] = "100";
   
      // Create query condition
      dds::sub::cond::QueryCondition query_condition(
          dds::sub::Query(reader, "x > %0 AND x < %1", query_parameters),
          dds::sub::status::DataState::any_data());

  
  
• You can use a QueryCondition in a WaitSet: see Waiting for Condition(s) to trigger
• And to query for data in a DataReader: see Selecting what samples to read
• To modify the filter criteria you can use dds::sub::cond::QueryCondition::parameters (similar to dds::topic::ContentFilteredTopic::filter_parameters)
• This example shows how to create a condition with a handler that takes the samples received by a DataReader and selected by the QueryCondition's filter.

      using dds::sub::cond::QueryCondition;
      
      QueryCondition query_condition2(
          dds::sub::Query(reader, "x > %0 AND x < %1", query_parameters),
          dds::sub::status::DataState::any_data(),
          // The handler function singature allows receiving the related condition
          // as a parameter (it also allows zero arguments).
          [&reader](dds::core::cond::Condition condition) 
          {
              // Downcast a Condition (a reference type) into a QueryCondition
              auto condition_as_qc = 
                      dds::core::polymorphic_cast<QueryCondition>(condition);
   
              // Use the condition's filter to select specific samples
              auto samples = reader.select().condition(condition_as_qc).take();
              for (auto& sample : samples) {
                  std::cout << "Sample received: " << sample << std::endl;
              }
          });

Filtering Performance

Although RTI Connext supports filtering on any field or combination of fields using the SQL syntax of the built-in filter, filters for keyed topics that filter solely on the contents of key fields have the potential for much higher performance. This is because for key-only filters, the dds::sub::DataReader caches the results of the filter (pass or not pass) for each instance. When another sample of the same instance is seen at the dds::sub::DataReader, the filter results are retrieved from the cache, dispensing with the need to call the filter function.

This optimization applies to all filtering using the built-in SQL filter, performed by the dds::sub::DataReader, for either dds::topic::ContentFilteredTopic or dds::sub::cond::QueryCondition. This does not apply to filtering perfomed for dds::topic::ContentFilteredTopic by the dds::pub::DataWriter.