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 parallels the behavior of the Schema tab within a Dataset’s Settings UI.
The only expected header is X-Honeycomb-Team
, which is your API key, and it is required.
The API key must have the Manage Queries and Columns permission.
Learn more about API keys.
Derived Columns have the following fields:
Field | Type | Optional | Notes |
---|---|---|---|
id |
string | read-only | Returned in response bodies; this is a base58 encoded string. (“The encoded data contains only alphanumerical characters, and avoids the easily confused characters 0, i, l and O (zero, india, lima, capital oscar).") |
alias |
string | no | |
description |
string | yes, default=”" | |
expression |
string | no | See Derived Column syntax |
Derived Columns are created by sending a POST request to /1/derived_columns/<DATASET_NAME>
.
The body should be a JSON encoded object.
Response status should be 201
, and the body will contain the created object, including its id
.
curl https://api.honeycomb.io/1/derived_columns/$DATASET \
-X POST \
-H "X-Honeycomb-Team: YOUR_API_KEY" \
-d '{"alias": "always_one", "expression": "MAX(1)", "description": "MAX(1) is always 1"}' \
{
"id": "mYVfSPi4s75",
"alias": "always_one",
"description": "MAX(1) is always 1",
"expression": "MAX(1)"
}
A Derived Column may be updated, by sending a PUT request to /1/derived_columns/<dataset>/<derived_column_id>
.
The PUT request should have as its body a JSON object containing all the user-settable fields for this Derived Column, including any updated values. (That is, it is a PUT request, not a PATCH applying a partial update.)
When a Derived Column has been successfully updated, the API returns code 200
and the updated Derived Column as the body of the response.
curl https://api.honeycomb.io/1/derived_columns/$DATASET/$DERIVED_COLUMN_ID
-X PUT \
-H "X-Honeycomb-Team: YOUR_API_KEY"
-d '{"alias": "always_one", "expression": "MAX(1)", "description": "MAX(1) is always always always 1"}'
{
"id": "mYVfSPi4s75",
"alias": "always_one",
"description": "MAX(1) is always always always 1",
"expression": "MAX(1)"
}
A Derived Column may be deleted, by sending a DELETE request to /1/derived_columns/<dataset>/<derived_column_id>
.
A successful response will have status code 204
and an empty body.
A Derived Column used by a SLO, Trigger, or Board cannot be deleted without removing or modifying the SLO, Trigger, or Board.
curl https://api.honeycomb.io/1/derived_columns/$DATASET_SLUG/$DERIVED_COLUMN_ID \
-H "X-Honeycomb-Team: YOUR_API_KEY" \
-X DELETE
A singular Derived Column in a dataset may be retrieved by sending a GET
request to /1/derived_columns/<DATASET_NAME>/<DERIVED_COLUMN_ID>
.
curl https://api.honeycomb.io/1/derived_columns/$DATASET_SLUG/$DERIVED_COLUMN_ID \
-X GET \
-H "X-Honeycomb-Team: YOUR_API_KEY"
{
"id": "mYVfSPi4s75",
"alias": "always_one",
"description": "MAX(1) is always always always 1",
"expression": "MAX(1)"
}
A Derived Column in a dataset may be retrieved by sending a GET
request to /1/derived_columns/<DATASET_NAME>?alias=<ALIAS>
.
curl https://api.honeycomb.io/1/derived_columns/$DATASET_SLUG?alias=$ALIAS \
-X GET \
-H "X-Honeycomb-Team: YOUR_API_KEY"
{
"id": "mYVfSPi4s75",
"alias": "always_one",
"description": "MAX(1) is always always always 1",
"expression": "MAX(1)"
}
All the Derived Columns in a dataset may be retrieved by sending a GET
request to /1/derived_columns/<DATASET_NAME>
.
A successful response will return HTTP 200
and a JSON list of all Derived Column objects for the dataset.
curl https://api.honeycomb.io/1/derived_columns/$DATASET_SLUG \
-X GET \
-H "X-Honeycomb-Team: YOUR_API_KEY"
Honeycomb Classic customers do not have Environments and therefore cannot use Environment derived columns.
Honeycomb supports derived columns that are applied to any Dataset in your Environment. Environment derived columns allow you to define the derived column expression once and then Honeycomb will run that expression against each dataset.
Derived columns that target all the Datasets within an Environment can be created and read with the same APIs as above, using the special __all__
token in the URL instead of a Dataset name.
curl https://api.honeycomb.io/1/derived_columns/__all__ \
-X POST \
-H "X-Honeycomb-Team: YOUR_API_KEY" \
-d '{"alias": "always_one", "expression": "MAX(1)", "description": "MAX(1) is always 1"}' \
Did you find what you were looking for?