logo

Derived Columns

Derived columns allow you to run queries based on the value of an expression that is derived from the columns in an event.

This API allows you to list, create, update, and delete derived columns in a dataset or across a whole environment, paralleling the behavior of the Schema tab within a Dataset's or Environment's Settings UI.

Authorization

The API key must have the Manage Queries and Columns permission. Learn more about API keys here.

Create a Derived Column

Create a derived column. Derived columns allow you to run queries based on the value of an expression that is derived from the columns in an event.

Securityapi_key
Request
path Parameters
datasetSlug
required
string

The dataset slug or use __all__ for endpoints that support environment-wide operations.

Request Body schema: application/json
required
alias
required
string [ 1 .. 255 ] characters

The human-readable name of the derived column, as it will be referenced when building queries.

expression
required
string [ 1 .. 4095 ] characters

The expression to evaluate to construct this derived column's value. Refer to the Derived Column Reference.

description
string <= 255 characters
Default: ""

A human-readable description for the derived column that displays in the UI.

Responses
201

Success

400

The provided request body was invalid. Most APIs will return a DetailedError for this condition, explaining what went wrong, but some older APIs only return a GenericError.

401

Unauthorized

404

Not Found

post/1/derived_columns/{datasetSlug}
Request samples
application/json
{
  • "alias": "string",
  • "expression": "string",
  • "description": ""
}
Response samples
application/json
{
  • "id": "yUheCUmgZ8p",
  • "alias": "one",
  • "description": "just one",
  • "expression": "INT(1)",
  • "created_at": "2022-07-26T22:38:04Z",
  • "updated_at": "2022-11-16T17:34:01Z"
}

List all Derived Columns

Get all the Derived Columns in a dataset or environment. With the ?alias=X query parameter, can return a single derived column by its alias.

Securityapi_key
Request
path Parameters
datasetSlug
required
string

The dataset slug or use __all__ for endpoints that support environment-wide operations.

query Parameters
alias
string

The derived column alias.

Responses
200

When listing all columns, an array of DerivedColumn objects will be returned. When using key_name, will return a single DerivedColumn object if found.

401

Unauthorized

404

Not Found

get/1/derived_columns/{datasetSlug}
Request samples 
Response samples 
application/json
[ ]
Get a Derived Column
Securityapi_key 
Request 
path Parameters
datasetSlug
required
string
The dataset slug or use __all__ for endpoints that support environment-wide operations.


 
derivedColumnId
required
string
Unique identifier (ID) of a derived column.


 
Responses 
200
Success


400
The provided request body was invalid. Most APIs will return a DetailedError for this condition, explaining what went wrong, but some older APIs only return a GenericError.


401
Unauthorized


404
Not Found


get/1/derived_columns/{datasetSlug}/{derivedColumnId}
Request samples 
Response samples 
application/json
{
  • "id": "yUheCUmgZ8p",
  • "alias": "one",
  • "description": "just one",
  • "expression": "INT(1)",
  • "created_at": "2022-07-26T22:38:04Z",
  • "updated_at": "2022-11-16T17:34:01Z"
}
Update a Derived Column
Update a derived column.


Securityapi_key 
Request 
path Parameters
datasetSlug
required
string
The dataset slug or use __all__ for endpoints that support environment-wide operations.


 
derivedColumnId
required
string
Unique identifier (ID) of a derived column.


 
Request Body schema: application/json
required
alias
required
string  [ 1 .. 255 ] characters 
The human-readable name of the derived column, as it will be referenced when building queries.


 
expression
required
string  [ 1 .. 4095 ] characters 
The expression to evaluate to construct this derived column's value. Refer to the Derived Column Reference.


 
description
string  <= 255 characters 
 Default:  ""
A human-readable description for the derived column that displays in the UI.


 
Responses 
200
Success


400
The provided request body was invalid. Most APIs will return a DetailedError for this condition, explaining what went wrong, but some older APIs only return a GenericError.


401
Unauthorized


404
Not Found


put/1/derived_columns/{datasetSlug}/{derivedColumnId}
Request samples 
application/json
{
  • "alias": "string",
  • "expression": "string",
  • "description": ""
}
Response samples 
application/json
{
  • "id": "string",
  • "alias": "string",
  • "expression": "string",
  • "description": "",
  • "created_at": "string",
  • "updated_at": "string"
}
Delete a Derived Column
Delete a derived column. Note: A Derived Column used by a SLO, Trigger, or Board cannot be deleted without removing or modifying the SLO, Trigger, or Board first.


Securityapi_key 
Request 
path Parameters
datasetSlug
required
string
The dataset slug or use __all__ for endpoints that support environment-wide operations.


 
derivedColumnId
required
string
Unique identifier (ID) of a derived column.


 
Responses 
204
Success - no content


400
The provided request body was invalid. Most APIs will return a DetailedError for this condition, explaining what went wrong, but some older APIs only return a GenericError.


401
Unauthorized


404
Not Found


delete/1/derived_columns/{datasetSlug}/{derivedColumnId}
Request samples 
Response samples 
{}
➔ Next to Events