Skip to main content

Event Delivery Filters

PhotonIQ Event Delivery offers advanced filtering capabilities, allowing users to specify the exact events they want to receive. By leveraging the PostgreSQL SELECT statement syntax, users can create filters that customize the event stream to their needs. This page outlines how to construct these queries, providing syntax guidelines, use cases, and examples.

Filters syntax​

Filters are defined in a JSON format, which includes fields to specify the desired event criteria. The fundamental structure of a filter includes:

  • action: Specifies the filter action, such as "add" to add new filters or "remove" to remove existing filters. This is only supported for WebSockets since messages cannot be sent from the client to the server in SSE. Refer to Dynamic filter management for more details.

  • initialData: When set to TRUE, returns the original data after subscribing to a stream. When set to FALSE, it only subscribes without returning the original data. The default is FALSE.

  • compress: Indicates if messages should be sent by the server in gz and base64 encoded format. The default is FALSE.

  • once: A boolean flag (TRUE or FALSE), indicating whether the filter should be applied just once. By default, it is FALSE.

  • queries: An array of SELECT statements defining the specific events to filter.

The SELECT syntax follows the SQL format, allowing you to specify conditions (WHERE), use logical operators (AND, OR), and select specific/all(*) fields within a collection or stream. Nested JSON attributes can also be referenced using dot notation, like details.phone while selecting fields within the stream.

Example JSON filter structure

{
  "action": "add",
  "once": "FALSE",
  "initialData":"FALSE",
  "compress": "FALSE",
  "queries": [
    "select * from CollectionName where condition1",
    "select fieldName from CollectionName where condition2 OR condition3"
  ]
}

Filter use cases and examples​

Using event delivery queries allows for highly customizable data streams tailored to various application needs. Whether monitoring real-time updates from a specific dataset or filtering changes based on specific criteria, these queries ensure your application processes only the most relevant information.

This section demonstrates how to subscribe to and filter events using practical examples. These examples highlight the flexibility of event delivery queries in EDS, allowing precise control over the data stream. You can interact with the PhotonIQ Event Delivery Service using wscat for WebSockets or curl for SSE.

Queries​

To subscribe to events using EDS, send a request to the Subscribe to Stream API. It requires the following fields:

  • EDS host: The host where the EDS service is running.
  • x-customer-id: This is used to identify the user making the request.
  • type: Type of subscription (e.g., collection).
  • filters:Fields to specify the desired event criteria.
  • API key: This is used to authenticate the request.
info

Contact Macrometa for your EDS host, API key, and Customer ID.

Curl currently has no support for WebSockets, you can use wscat to send a request to the Subscribe to Stream API via WebSockets as shown below:

  wscat -c 'wss://<eds-host>/api/es/v1/subscribe?apikey=<api_key>&type=collection&x-customer-id=<x-customer-id>&filters={"action": "add", "once": "FALSE", "queries": ["select fieldName from CollectionName"]}'

Subscribe to specific field changes

Subscribing to specific field changes is useful when monitoring a specific attribute of a dataset for changes — such as price adjustments in a product catalog or status updates in a task tracking system. For example, an e-commerce platform might use this to update the UI in real-time when a product price changes, enhancing the customer experience.

  wscat -c 'wss://<eds-host>/api/es/v1/subscribe?apikey=<api_key>&type=collection&x-customer-id=<x-customer-id>&filters={"action": "add", "once": "FALSE", "queries": ["select fieldName from CollectionName"]}'

The above command subscribes to changes in fieldName within CollectionName.

Subscribe to all events in a Collection

This is particularly beneficial for applications that need to maintain a real-time view of an entire dataset, such as a dashboard displaying the latest metrics across various data points or a live feed of social media posts. For example, a monitoring tool could use this to alert operators of any changes across all monitored systems, ensuring swift response to incidents.

  wscat -c 'wss://<eds-host>/api/es/v1/subscribe?apikey=<api_key>&type=collection&x-customer-id=<x-customer-id>&filters={"action": "add", "once": "FALSE", "queries": ["select * from CollectionName"]}'

This command subscribes to all changes within CollectionName.

Conditional Subscription

Conditional subscription is ideal for situations where events are only relevant under certain conditions, reducing noise and focusing on significant data changes. For example, in a logistics application, this could be used to alert users only when shipments are delayed by more than a day or when inventory levels fall below a critical threshold, enabling timely decision-making.

  wscat -c 'wss://<eds-host>/api/es/v1/subscribe?apikey=<api_key>&type=collection&x-customer-id=<x-customer-id>&filters={"action": "add", "once": "FALSE", "queries": ["select specificField from CollectionName where condition"]}'

The command above subscribes to changes in specificField when condition is met.

Dynamic filter management​

Filters can be dynamically added or removed after the initial subscription request via the WebSocket. This flexibility allows users to adapt to changing requirements or focus areas without needing to establish a new connection or subscription.

Removing filters: Removing filters is useful in scenarios where the relevance of certain data changes over time. For instance, in a financial application, you might remove filters related to stock prices of specific companies after the market closes or when a trading decision has been made. This helps in focusing resources and attention on other relevant data streams without disruption.

To remove a filter from an existing subscription, use this command:

{"action": "remove", "queries": ["select * from CollectionName where condition"]}

Adding filters: Adding new filters is particularly valuable when new information requirements arise, such as tracking additional metrics or focusing on a new set of data points. For example, in an IoT application monitoring environmental sensors, you might add filters to track temperature fluctuations in additional rooms or buildings as they become areas of interest, enabling tailored alerts and data analysis without interrupting the existing data flow. To add new filters to an existing subscription, use this command:

{"action": "add", "once": "FALSE", "queries": ["select fieldName from CollectionName", "select anotherField from CollectionName where condition"]}