DataLab saved queries


A saved query is a DataLab selection stored with a name, plus the actions configured to run on what it finds.

People build and save queries in Operator's DataLab, and arrange them in groups. Dashboards, Navigator menu items and other queries refer to saved queries. You can read about the Navigator menu item in Item: DataLab query.

This article will cover how to manage saved query and query group records. The selection they hold is described in DataLab queries, and the actions in DataLab actions.

Data model

Below is the core data model for a saved query. You can save a record without populating the action.

interface ISavedQuery {
    // Exclude this value for new records.
    "ID"?: number;
    // (60) Optional unique key you choose. Must not be a number.
    "Key"?: string;
    // (200) Name shown in Operator's list.
    "DisplayName": string;
    "Description"?: string;
    // The selection. See the DataLab queries page.
    "PrimarySelectionCriteria"?: ISelection;
    // The actions configured on the query. See "Matching action".
    "MatchingEntitiesAction"?: IMatchingEntitiesAction;
    // Set by the server on save: true when MatchingEntitiesAction holds an action.
    "IsActionable"?: boolean;
    // ID of the group the query is in. 0 or missing means ungrouped.
    "QueryGroup.ID"?: number;
    // Order among queries in the same group. Smaller numbers are shown first.
    "DisplayOrder"?: number;
    // Set by the server.
    "CreatedBy.User.ID"?: string;
    "Created"?: string;
    "Updated"?: string;
}

Matching action

"MatchingEntitiesAction" holds the action Operator runs on the primary selection, and optionally a secondary selection with its own action. Operator runs the primary action with "PrimarySelectionCriteria" as the "PrimarySelection", and the secondary action with both selections. The server stores the object as given and only reads it to set "IsActionable".

interface IMatchingEntitiesAction {
    // An action, as described on the DataLab actions page.
    // "ActionType": "secondarySelection" marks a query whose primary selection feeds a secondary one.
    "Primary"?: IAction;
    // The secondary selection, when Primary is "secondarySelection".
    "SecondarySelectionCriteria"?: ISelection;
    // The action to run on the two selections.
    "Secondary"?: IAction;
}

// Eg: Tag every match.
{
    "Primary": {
        "ActionType": "layer",
        "Layer": { "Operator": "add", "OperandA": [ 1 ] }
    }
}

Requesting saved queries

The list is ordered by name and leaves out "PrimarySelectionCriteria" and "MatchingEntitiesAction". Get a query by ID or Key for the full record.

Get a list of saved queries

Response
interface IResponse {
    "Items": ISavedQuery[];
    // Present with ExpandGroups.
    "Groups"?: IQueryGroup[];
}
Javascript example

Get a saved query by ID or Key

Response
// The response is the saved query record directly.
// See the data model above for the record structure.
Javascript example

Create and update saved queries

An update only changes the fields you send. A Key another saved query already uses is refused.

Create or update a saved query

Request body
// See the data model above for the record structure.
type IPostBody = ISavedQuery;
Response
// The response is the saved query record directly.
// See the data model above for the record structure.
Javascript example

Delete a saved query

We don't provide any bulk deletion but you can delete by record ID. Deleting an ID that does not exist still succeeds.

Delete a saved query

Javascript example

Query groups

A query group is a named folder for saved queries in Operator. A query joins a group through its "QueryGroup.ID".

interface IQueryGroup {
    // Exclude this value for new records.
    "ID"?: number;
    // (60) Optional unique key you choose. Must not be a number.
    "Key"?: string;
    // (30) The group name.
    "DisplayName": string;
    "Description"?: string;
    // Stored as given.
    "Settings"?: any;
    // Order among groups. Smaller numbers are shown first.
    "DisplayOrder"?: number;
    // Set by the server.
    "Created"?: string;
    "Updated"?: string;
}

Get a list of query groups

Response
interface IResponse {
    "Items": IQueryGroup[];
}
Javascript example

Create or update a query group

Response
// The response is the query group record directly.
Javascript example

Delete a query group

Response
interface IResponse {
    // False when no group had the ID.
    "Deleted": boolean;
    "QueryAction": "UNGROUP" | "DELETE";
    "QueryActionMessage": string;
    "QueriesUpdated": number;
    "QueriesDeleted": number;
}
Javascript example