---
title: "Data Transforms"
section: "API Reference"
route: /apidatatransform
account: {accountId}
bruce_api: https://{accountId}.api.nextspace.host
guardian_api: https://guardian.nextspace.host
---
# Data Transforms

A Data Transform is a saved, named Data Mapping that you run over Entities that already exist. Each Entity is both the source and the target of the mapping, so a Data Transform can copy, combine, look up or recalculate attribute values in place.

Data Transforms are managed in Operator and belong to an Entity Type. You run one from a DataLab action, or while re-indexing an Entity Type.

This article will cover how to manage Data Transform records and how to run them. You can read about the mapping itself, including every mapping function, in [Data Mapping](/apidatamapping).

## Data model

Below is the data model for a Data Transform.

```typescript
interface IDataTransform {
    // Unique ID for the Data Transform.
    // Exclude this value for new records.
    ID?: number;
    // The Entity Type this Data Transform belongs to.
    // Set when the record is created and not changed by updates.
    "EntityType.ID": string;
    // Human readable name. Limited to 100 characters.
    // A DataLab action can name the Data Transform by this value instead of its ID.
    Name: string;
    // Description of what the Data Transform does.
    Description?: string;
    // The mapping to run over each Entity.
    // See the Data Mapping page for the structure.
    DataMapping: IDataMapping;
    // Schema of the source side shown in the Operator editor.
    // Data validation reports read it to list the source attributes.
    SourceDataSchema?: IDataSchema;
    // Schema of the target side shown in the Operator editor.
    // The DataLab action adds its attributes to the Data Schema of each Entity Type it changes.
    DestinationDataSchema?: IDataSchema;
    // What the requesting user can do with this record.
    // A combination of "C" (create), "R" (read), "U" (update) and "D" (delete). Eg: "RU".
    // Returned when getting a single record, and ignored when saving.
    Permission?: string;
    // ISO 8601 date time strings, set by the API.
    Created?: string;
    Updated?: string;
}
```

Operator fills both schemas from the Entity Type's own Data Schema when you create a Data Transform. You can read about the schema structure in [Entity Type: Data Schema](/apientitytypedataschema).

## Requesting records

You can request every Data Transform in the account, the ones belonging to one Entity Type, or a single one. Lists are sorted by name, include the mapping and both schemas, and leave out Data Transforms whose Entity Type has been deleted.

Access is checked against the Data Transform permissions of the requesting user.

### Get a list of Data Transforms

```http
GET https://{accountId}.api.nextspace.host/dataTransforms
```

**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. |

**Response**

```typescript
interface IResponse {
    // Array of Data Transform records, without "Permission".
    // See the data model above for the record structure.
    Items: IDataTransform[];
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/dataTransforms";
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 list of Data Transforms for an Entity Type

```http
GET https://{accountId}.api.nextspace.host/entityType/{entityType_id}/dataTransforms
```

**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. |
| `{entityType_id}` | path | yes | The ID of the Entity Type to get the Data Transforms of. |

**Response**

```typescript
interface IResponse {
    // Array of Data Transform records, without "Permission".
    // See the data model above for the record structure.
    Items: IDataTransform[];
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/entityType/{entityType_id}/dataTransforms";
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 Data Transform by ID

```http
GET https://{accountId}.api.nextspace.host/dataTransform/{dataTransform_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. |
| `{dataTransform_id}` | path | yes | The ID of the Data Transform to get. |

**Response**

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

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/dataTransform/{dataTransform_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);
});
```

The same request scoped to an Entity Type returns a 404 error when the Data Transform belongs to a different Entity Type.

### Get Data Transform by ID for an Entity Type

```http
GET https://{accountId}.api.nextspace.host/entityType/{entityType_id}/dataTransform/{dataTransform_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. |
| `{entityType_id}` | path | yes | The ID of the Entity Type the Data Transform belongs to. |
| `{dataTransform_id}` | path | yes | The ID of the Data Transform to get. |

**Response**

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

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/entityType/{entityType_id}/dataTransform/{dataTransform_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 records

You can create a record by performing a POST request with the ID as "0". If you specify an existing ID then it'll update the record. Both return the saved record.

When updating, only the properties you include are changed. The mapping and each schema are replaced as a whole. The Entity Type is set on create: from the URL when you use the Entity Type route, otherwise from "EntityType.ID" in the body.

### Create or update Data Transform

```http
POST https://{accountId}.api.nextspace.host/dataTransform/{dataTransform_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. |
| `{dataTransform_id}` | path | yes | The ID of the Data Transform to update. Set as 0 to create a new record. |

**Request body**

```typescript
// Body should be the Data Transform JSON as specified at the top of the article.
```

**Example request body**

```json
{
    "EntityType.ID": "my-entity-type-id",
    "Name": "Fill full name",
    "DataMapping": {
        "Functions": [
            {
                "ID": "join-name",
                "Function": "Concatenate",
                "Inputs": [
                    "A",
                    "B"
                ],
                "Settings": {
                    "Delimiter": " "
                }
            }
        ],
        "Connections": [
            {
                "Left": {
                    "Panel": "left",
                    "Path": "\"first_name\"",
                    "Key": "out"
                },
                "Right": {
                    "Panel": "function",
                    "Path": "join-name",
                    "Key": "A"
                }
            },
            {
                "Left": {
                    "Panel": "left",
                    "Path": "\"last_name\"",
                    "Key": "out"
                },
                "Right": {
                    "Panel": "function",
                    "Path": "join-name",
                    "Key": "B"
                }
            },
            {
                "Left": {
                    "Panel": "function",
                    "Path": "join-name",
                    "Key": "Result"
                },
                "Right": {
                    "Panel": "right",
                    "Path": "\"full_name\"",
                    "Key": "in"
                }
            }
        ]
    }
}
```

**Response**

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

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/dataTransform/{dataTransform_id}";
const method = "post";
const token = "your-token";
const body = {
    "EntityType.ID": "my-entity-type-id",
    "Name": "Fill full name",
    "DataMapping": {
        "Functions": [
            {
                "ID": "join-name",
                "Function": "Concatenate",
                "Inputs": [
                    "A",
                    "B"
                ],
                "Settings": {
                    "Delimiter": " "
                }
            }
        ],
        "Connections": [
            {
                "Left": {
                    "Panel": "left",
                    "Path": "\"first_name\"",
                    "Key": "out"
                },
                "Right": {
                    "Panel": "function",
                    "Path": "join-name",
                    "Key": "A"
                }
            },
            {
                "Left": {
                    "Panel": "left",
                    "Path": "\"last_name\"",
                    "Key": "out"
                },
                "Right": {
                    "Panel": "function",
                    "Path": "join-name",
                    "Key": "B"
                }
            },
            {
                "Left": {
                    "Panel": "function",
                    "Path": "join-name",
                    "Key": "Result"
                },
                "Right": {
                    "Panel": "right",
                    "Path": "\"full_name\"",
                    "Key": "in"
                }
            }
        ]
    }
};

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 Data Transform for an Entity Type

```http
POST https://{accountId}.api.nextspace.host/entityType/{entityType_id}/dataTransform/{dataTransform_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. |
| `{entityType_id}` | path | yes | The ID of the Entity Type the Data Transform belongs to. Updating a Data Transform of a different Entity Type returns a 404 error. |
| `{dataTransform_id}` | path | yes | The ID of the Data Transform to update. Set as 0 to create a new record. |

**Request body**

```typescript
// Body should be the Data Transform JSON as specified at the top of the article.
// "EntityType.ID" is taken from the URL.
```

**Response**

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

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/entityType/{entityType_id}/dataTransform/{dataTransform_id}";
const method = "post";
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);
});
```

## Delete a record

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

### Delete Data Transform

```http
DELETE https://{accountId}.api.nextspace.host/dataTransform/{dataTransform_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. |
| `{dataTransform_id}` | path | yes | The ID of the Data Transform to delete. |

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/dataTransform/{dataTransform_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);
});
```

### Delete Data Transform for an Entity Type

```http
DELETE https://{accountId}.api.nextspace.host/entityType/{entityType_id}/dataTransform/{dataTransform_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. |
| `{entityType_id}` | path | yes | The ID of the Entity Type the Data Transform belongs to. Deleting a Data Transform of a different Entity Type returns a 404 error. |
| `{dataTransform_id}` | path | yes | The ID of the Data Transform to delete. |

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/entityType/{entityType_id}/dataTransform/{dataTransform_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);
});
```

## Running a Data Transform

Running a Data Transform maps each Entity onto itself. The mapping output is merged into the Entity, so attributes the mapping does not write keep their values. A mapping cannot change an Entity's ID, Entity Type or audit values.

The DataLab "data-transform" action runs a Data Transform over the Entities a DataLab query finds, named by its ID or its name. It also adds the attributes of "DestinationDataSchema" to the Data Schema of each Entity Type it changes. You can read about it in [DataLab actions](/apidatalabactions).

You can also run a Data Transform over every Entity of an Entity Type while re-indexing it. Every Entity the mapping changes is saved again, and "reSaveAll" saves the rest as well. The request starts a Pending Action, which you can follow as described in [Pending Actions](/apipendingaction).

### Re-index an Entity Type with a Data Transform

```http
POST https://{accountId}.api.nextspace.host/entityType/{entityType_id}/reindex?dataTransformID={dataTransform_id}&reSaveAll={reSaveAll}&calcAssemblyLocations={calcAssemblyLocations}&sources={sources}
```

**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. |
| `{entityType_id}` | path | yes | The ID of the Entity Type whose Entities are re-indexed. |
| `dataTransformID={dataTransform_id}` | query | no | The ID of the Data Transform to run over each Entity. Leave out to re-index without one. |
| `reSaveAll={reSaveAll}` | query | no | Set to true to save every Entity, rather than only the ones that need it. Default is false. |
| `calcAssemblyLocations={calcAssemblyLocations}` | query | no | Set to true to calculate and save positions for assembly Entities. This is slow, so only use it when you need the positions. Default is false. |
| `sources={sources}` | query | no | Set to false to skip loading values from the Entity Type's external sources. Default is true. |

**Response**

```typescript
interface IResponse {
    // ID of the Pending Action running the re-index.
    "PendingActionID": number;
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/entityType/{entityType_id}/reindex";
const method = "post";
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/apidatatransform
