---
title: "DataLab saved queries"
section: "API Reference"
route: /apidatalabsavedqueries
account: {accountId}
bruce_api: https://{accountId}.api.nextspace.host
guardian_api: https://guardian.nextspace.host
---
# 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](/apimenuitem#apimenuitemdatalab).

This article will cover how to manage saved query and query group records. The selection they hold is described in [DataLab queries](/apidatalabqueries), and the actions in [DataLab actions](/apidatalabactions).

## Data model

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

```typescript
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".

```typescript
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

```http
GET https://{accountId}.api.nextspace.host/entities/datalab/savedQueries?ExpandGroups={true}&IsActionableOnly={true}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `ExpandGroups={true}` | query | no | Also return the query groups as "Groups". Default is false. |
| `IsActionableOnly={true}` | query | no | Only return queries that have an action. Default is false. |

**Response**

```typescript
interface IResponse {
    "Items": ISavedQuery[];
    // Present with ExpandGroups.
    "Groups"?: IQueryGroup[];
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/entities/datalab/savedQueries";
const method = "get";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

### Get a saved query by ID or Key

```http
GET https://{accountId}.api.nextspace.host/entities/datalab/savedQuery/{query_id}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{query_id}` | path | yes | The ID or Key of the saved query to get. |

**Response**

```typescript
// The response is the saved query record directly.
// See the data model above for the record structure.
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/entities/datalab/savedQuery/{query_id}";
const method = "get";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

## 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

```http
POST https://{accountId}.api.nextspace.host/entities/datalab/savedQuery/{query_id}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{query_id}` | path | yes | The ID of the saved query to update. Set as 0 to create a new record. |

**Request body**

```typescript
// See the data model above for the record structure.
type IPostBody = ISavedQuery;
```

**Example request body**

```json
{
    "DisplayName": "Active pumps",
    "PrimarySelectionCriteria": {
        "Items": [
            {
                "key": "entityType",
                "EntityType": {
                    "EntityType.ID": "my-entity-type-id"
                }
            }
        ]
    }
}
```

**Response**

```typescript
// The response is the saved query record directly.
// See the data model above for the record structure.
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/entities/datalab/savedQuery/{query_id}";
const method = "post";
const token = "your-token";
const body = {
    "DisplayName": "Active pumps",
    "PrimarySelectionCriteria": {
        "Items": [
            {
                "key": "entityType",
                "EntityType": {
                    "EntityType.ID": "my-entity-type-id"
                }
            }
        ]
    }
};

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

## 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

```http
DELETE https://{accountId}.api.nextspace.host/entities/datalab/savedQuery/{query_id}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{query_id}` | path | yes | The ID of the saved query to delete. |

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/entities/datalab/savedQuery/{query_id}";
const method = "delete";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

## Query groups

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

```typescript
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

```http
GET https://{accountId}.api.nextspace.host/entities/datalab/savedQueryGroups
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |

**Response**

```typescript
interface IResponse {
    "Items": IQueryGroup[];
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/entities/datalab/savedQueryGroups";
const method = "get";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

### Create or update a query group

```http
POST https://{accountId}.api.nextspace.host/entities/datalab/savedQueryGroup/{group_id}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{group_id}` | path | yes | The ID of the group to update. Set as 0 to create a new record. |

**Example request body**

```json
{
    "DisplayName": "Asset checks",
    "DisplayOrder": 1
}
```

**Response**

```typescript
// The response is the query group record directly.
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/entities/datalab/savedQueryGroup/{group_id}";
const method = "post";
const token = "your-token";
const body = {
    "DisplayName": "Asset checks",
    "DisplayOrder": 1
};

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

### Delete a query group

```http
DELETE https://{accountId}.api.nextspace.host/entities/datalab/savedQueryGroup/{group_id}?QueryAction={UNGROUP}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{group_id}` | path | yes | The ID of the group to delete. |
| `QueryAction={UNGROUP}` | query | no | What happens to the group's queries. UNGROUP keeps them without a group, DELETE deletes them. Default is UNGROUP. |

**Response**

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

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/entities/datalab/savedQueryGroup/{group_id}";
const method = "delete";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

---

Urls on this page are resolved for account `{accountId}`.
Site index: https://docs.nextspace.host/llms.txt · whole site in one file: https://docs.nextspace.host/llms-full.txt
Human-readable version of this page: https://docs.nextspace.host/apidatalabsavedqueries
