Visual Query

Analysts use Visual Query to search for records in the Information Store based on the values of specific properties, and on their relationships with other records. The records that they find depend on the structure of the queries that they create.

Starting from version 4.4.2 of i2 Analyze, you can write Visual Query services for your connectors. Analysts can then interrogate an external source in the same way as they query the Information Store, using the familiar tools in the web client and the Analyst's Notebook desktop client.

Example

The Visual Queries that analysts create have two parts:

  • The query structure, which indicates the types and relationships of the records they're interested in.
  • The query conditions, which apply to the items in the structure and specify some of the values in the records they want to find.

A Visual Query service that you create must examine the query structure that it receives in the request, and return a response containing records whose property values match the query conditions.

Note: In general, external data sources do not support the range of queries that are necessary for implementing unrestricted Visual Query operations across every record type they contain. When you write a Visual Query service, you can constrain the item types that analysts can use in their query structures, and the property types that they can use in query conditions.

Adding a new service

Adding a Visual Query service to your connector means calling the addVisualQueryService() method from the index.ts file that defines it. In the first argument to the method, you provide the service configuration, which places limits on the Visual Queries that analysts can create.

For example, you can use the paletteItemTypes field to say explicitly which item types appear (or do not appear) in the Visual Query structure editor:

addVisualQueryService(
  {
    name: 'Visual Query service with example restrictions',
    id: 'visual-query-service-with-example-restrictions',
    description:
      'A Visual Query service that does not allow query entities of type ET3 in query structures, and has operator usage rules and constraints',
    config: {
      paletteItemTypes: { mode: 'DENY', itemTypeIds: ['ET3'] },

Alternatively (or additionally), you can use the operatorUsageRules field to allow or deny the use of conditions that involve particular property types, aspects, or operators. A rule can apply to a single item type or to all available item types:

      operatorUsageRules: [
        // Deny the use of query conditions on all query items.
        {
          ruleType: 'DENY',
        },

        // Override the above. For query entities of type ET2
        // only, specifically allow conditions that use the BETWEEN operator
        // on YEAR aspects of property types EVE4 and EVE5.
        {
          ruleType: 'ALLOW',
          itemTypeId: 'ET2',
          propertyTypeIds: ['EVE4', 'EVE5'],
          operators: ['BETWEEN'],
          aspects: ['YEAR'],
        },

        // Override the above. For query entities of type ET1 only,
        // specifically allow conditions that use the EQUAL_TO or STARTS_WITH
        // operator on property type ADD5.
        {
          ruleType: 'ALLOW',
          itemTypeId: 'ET1',
          propertyTypeIds: ['ADD5'],
          operators: ['EQUAL_TO', 'STARTS_WITH'],
        },
      ],

Note: The rules that you can define here are equivalent to the rules that administrators can create to govern the behavior of Visual Queries against the Information Store. For more information, see Visual Query condition restrictions.

Finally, you can use the constraints field to restrict other features of the query structures that analysts can create:

      constraints: {
        // Can users specify which record types they want in results?
        outputSelectionSupported: true,

        // How many items in the query structure can have count conditions?
        maximumCountConditions: 1,

        // How many query links can appear in the query structure?
        maximumQueryLinkCount: 100,

        // How many query entities can have the 'Any' type?
        maximumAnyEntityTypeSupported: 1,

        // How many query links can have the 'Any' type?
        maximumAnyLinkTypeSupported: 2,
      },
    },
  },
  async ({ visualQuery, result }) => {
    // TODO: Implement the service
  }
);

Implementing the service

Taken as a whole, the Visual Query service configuration places limits on the contents of the visualQuery objects that your service receives.

A real service would search an external data source for records that match or correspond to the contents of visualQuery, and then populate the result with the records that it finds.

Note: Implementing a Visual Query service over an external source can be a complicated task, especially if the source isn't relational. i2 recommends engaging with its Services team to assist with the creation of Visual Query services.

Reload the connector configuration in i2 Analyze

To make a new service available, you must reload the connector so that i2 Analyze picks up the configuration changes. Just like when you deployed the connector for the first time, you can use the Admin Console.

  1. Open a web browser and navigate to https://i2analyze.eia:9443/opal/admin#/connectors.

  2. If you are prompted to log in, enter Jenny and Jenny as the username and password.

  3. Click the Reload gateway button.

Investigate in Analyst's Notebook

After you reload the gateway, you can see what happens when you use the connector from the Analyst's Notebook desktop client.

  1. Open Analyst's Notebook and log in when prompted.

  2. Click the External Searches button on the ribbon bar, and find the new Visual Query in the list.

  3. Click Open to start designing a Visual Query.

  4. Create the query structure, specify the query conditions, and then click Run to execute it.