Derived Columns API

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 Honeycomb Dataset Schema UI.

Authorization and Headers 🔗

The only expected header is X-Honeycomb-Team, which is your Team API key, and it is required. The API key must have the Manage Queries and Columns permission. Learn more about API keys.

Fields on a Derived Column 🔗

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

Create a Derived Column 🔗

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.

Create Example Request 🔗

curl https://api.honeycomb.io/1/derived_columns/$DATASET \
    -X POST \
    -H "X-Honeycomb-Team: $LIBHONEY_WRITE_KEY" \
    -d '{"alias": "always_one", "expression": "MAX(1)", "description": "MAX(1) is always 1"}' \

Create Example Response 🔗

{
  "id": "mYVfSPi4s75",
  "alias": "always_one",
  "description": "MAX(1) is always 1",
  "expression": "MAX(1)"
}

Update a Derived Column 🔗

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.

Update Example Request 🔗

curl https://api.honeycomb.io/1/derived_columns/$DATASET/$DERIVED_COLUMN_ID
    -X PUT \
    -H "X-Honeycomb-Team: $LIBHONEY_WRITE_KEY"
    -d '{"alias": "always_one", "expression": "MAX(1)", "description": "MAX(1) is always always always 1"}'

Update Example Response 🔗

{
  "id": "mYVfSPi4s75",
  "alias": "always_one",
  "description": "MAX(1) is always always always 1",
  "expression": "MAX(1)"
}

Delete a Derived Column 🔗

A successful response will have status code 204 and an empty body.

A Derived Column used by a SLO cannot be deleted without removing or modifying the SLO.

A Derived Column used by a Trigger should not be removed until the Trigger is removed or modified. There is currently no protection to prevent this removal from happening. If you find yourself having deleted a Derived Column in use by a Trigger, please contact Support via chat or email at support@honeycomb.io

Delete Example Request 🔗

curl https://api.honeycomb.io/1/derived_columns/$DATASET_SLUG/$DERIVED_COLUMN_ID \
    -H "X-Honeycomb-Team: $LIBHONEY_WRITE_KEY" \
    -X DELETE

Get One Derived Column 🔗

A singular Derived Column in a dataset may be retrieved by sending a GET request to /1/derived_columns/<DATASET_NAME>/<DERIVED_COLUMN_ID>.

Get One Example Request 🔗

curl https://api.honeycomb.io/1/derived_columns/$DATASET_SLUG/$DERIVED_COLUMN_ID \
    -X GET \
    -H "X-Honeycomb-Team: $LIBHONEY_WRITE_KEY"

Get One Example Response 🔗

{
  "id": "mYVfSPi4s75",
  "alias": "always_one",
  "description": "MAX(1) is always always always 1",
  "expression": "MAX(1)"
}

Get One Derived Column by Alias 🔗

A Derived Column in a dataset may be retrieved by sending a GET request to /1/columns/<DATASET_NAME>?alias=<ALIAS>.

Get One by Alias Example Request 🔗

curl https://api.honeycomb.io/1/derived_columns/$DATASET_SLUG?alias=$ALIAS \
    -X GET \
    -H "X-Honeycomb-Team: $LIBHONEY_WRITE_KEY"

Get One by Alias Example Response 🔗

{
  "id": "mYVfSPi4s75",
  "alias": "always_one",
  "description": "MAX(1) is always always always 1",
  "expression": "MAX(1)"
}

List All Derived Columns 🔗

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.

List All Example Request 🔗

curl https://api.honeycomb.io/1/derived_columns/$DATASET_SLUG \
    -X GET \
    -H "X-Honeycomb-Team: $LIBHONEY_WRITE_KEY"

Honeycomb.io Docs