Queries

In this tutorial we will cover queries.

This section assumes a connection has been established; see the getting started tutorial as necessary.

Queries are a way to discover symbols that are available to snapshot or subscribe to for a given data source. They can also be used to watch for any changes in the available symbols.

Tag expressions

To make a query a tag expression must be constructed into a string. A tag expression is a natural language syntax to search a specific data source for content. The format for a tag expression is:

tag=value [and tag=value]
tag=value [and tag!=value]

Specific tags are supported for different data sources, currently most tags will only work with the activ data source.

The supported tags are:

  • country
  • exchange
  • permission-id
  • region
  • table
  • type
  • symbol

All but the last of these tags are only supported in the activ data source.

Tag expressions can only be defined using the = or != operators with the righthand side being a simple value. The only exception to this rule is the symbol tag which can either be a fixed symbol or a trailing pattern (see later examples). Tag value pairs can be joined using the and operator. This is the only supported operator. All tag expression queries must include at least one = operator. Specifying only a != operator is not supported.

Tag examples

Some example tag expressions for the activ data source.

  • Query for all AAPL options in the US:
    type=option and country=US and symbol=AAPL/*
  • Query for all AAPL options on the Nasdaq exchange:
    type=option and exchange=Q and symbol=AAPL/*
  • Query for all US listing records:
    type=listing and country=US
  • Query for all regional AAPL options in the US:
    type=option and country=US and exchange!=O and symbol=AAPL/*

The following query on the platform data source will return all the available platform topics:

  • symbol=*

Making a query

The query method of Session query returns a QueryHandle. The callback interface provides the following callbacks:

  • Add - a single query result
  • Remove - a single topic removal
  • Status - the state of the query has changed

A query first searches for existing topics, calling the add callback for each result. Once complete the query will continue to watch for changes to the result set calling the add and remove callback methods when new topics are added or removed

Here is an example of a query for all us listing symbols that match CSIQ.*. In the example the initial snapshot of available topics only is processed and all Topic Ids are stored in an array for use later.

/* global activOneApi */
// You may have to update the userId and password fields below.
const user = "__ACTIV_SESSION_USER_ID__";
const password = "__ACTIV_SESSION_PASSWORD__";
const host = "aop-ny4-replay.activfinancial.com";

(async function() {
    try {
        const session = await activOneApi.connect({
            host,
            user,
            password,
            onLogMessage(logType, message) {
                console.log(message);
            }
        });

        let topicIds = [];
        // Initiate a topic query request.
        session.query({
            dataSourceId: activOneApi.DataSourceId.activ,
            tagExpression: "type=listing and country=US and symbol=CSIQ.*"
        },
        {
            onQueryAdd(topicId) {
                topicIds.push(topicId);
            },
            onQueryRemove(topicId) {
                console.log("Remove received for " + topicId.toString());
            },
            onQueryStatus(statusCode, isComplete) {
                if (activOneApi.StatusCode.success != statusCode)
                    console.error(`Error: ${activOneApi.StatusCode[statusCode]}`);
                else {
                    // Output all of the topic ids if the query is successful and complete.
                    console.log(topicIds);
                }
                
                // If we have completed the query either successfully or with an error then we close the query.
                return (activOneApi.StatusCode.success == statusCode) || isComplete;
            }
        });
    } catch (e) {
        console.error(`Failure: ${activOneApi.StatusCode[e]}`);
    }
})();
Try it out in the playground

Query Add

The add callback will be called for each topic that matches the query.

Query Remove

The remove callback will be called when a topic has been deleted from the platform and there is now no source available.

Query Status

The status callback will be called for changes to the state of the query. This status is indicated using the statusCode field. StatusCode.success`` indicating the initial snapshot of results is complete, and every other status code indicating a failure or error. If the boolean fieldisComplete` will be true then the query has failed and cannot recover.

Queries can also be used to discover topics that are related to an already known symbol. The format of these queries is:

symbol=<symbol> navigate=<relationship>

The relationship can provided to the query using either the RelationshipId number or as a string representing one of those relationship ids. The format of the string is lowercase with '-' characters to seperate words.

Some example navigation requests for the activ data source.

  • Query for all options for APPL.Q
    symbol=APPL.Q navigate=option-contract
  • Query for the company topic for APPL.Q
    symbol=APPL.Q navigate=company
  • Query for all ES future options
    symbol=ES/CMG.FOR navigate=future-option

Note that not all relationships are supported for every symbol.

Query Handle

The QueryHandle can also be used to process results of the query. The handle can be async iterated through as an async collection of QueryResult objects. A query result contains a statusCode property that indicates if there has been an error.

Also in this Section