Language

English Français 日本語 한국어 Español

Datadog Site

Site help
US1 US3 US5 EU AP1 AP2 US1-FED

Reference Tables

Auto-generated tag Reference Tables

Create reference table upload

POST https://api.ap1.datadoghq.com/api/v2/reference-tables/uploadshttps://api.ap2.datadoghq.com/api/v2/reference-tables/uploadshttps://api.datadoghq.eu/api/v2/reference-tables/uploadshttps://api.ddog-gov.com/api/v2/reference-tables/uploadshttps://api.datadoghq.com/api/v2/reference-tables/uploadshttps://api.us3.datadoghq.com/api/v2/reference-tables/uploadshttps://api.us5.datadoghq.com/api/v2/reference-tables/uploads

Overview

Create a reference table upload for bulk data ingestion

Request

Body Data (required)

Expand All

Field

Type

Description

data

object

The definition of CreateUploadRequestData object.

attributes

object

The definition of CreateUploadRequestDataAttributes object.

headers [required]

[string]

The headers of the file to upload.

part_count [required]

int32

The number of parts in the upload.

part_size [required]

int64

The size of each part in the upload in bytes. For multipart uploads (part_count > 1), all parts except the last one must be at least 5,000,000 bytes. For single-part uploads (part_count = 1), any size is allowed.

table_name [required]

string

The name of the reference table.

id

string

The ID of the upload.

type [required]

enum

Upload resource type. Allowed enum values: upload

default: upload

{
  "data": {
    "attributes": {
      "headers": [
        ""
      ],
      "part_count": 3,
      "part_size": 10000000,
      "table_name": ""
    },
    "id": "string",
    "type": "upload"
  }
}

Response

Created

The definition of CreateUploadResponse object.

Expand All

Field

Type

Description

data

object

The definition of CreateUploadResponseData object.

attributes

object

The definition of CreateUploadResponseDataAttributes object.

part_urls

[string]

The URLs of the parts in the upload.

id

string

The ID of the upload.

type [required]

enum

Upload resource type. Allowed enum values: upload

default: upload

{
  "data": {
    "attributes": {
      "part_urls": []
    },
    "id": "string",
    "type": "upload"
  }
}

Bad Request

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Forbidden

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Too many requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example

                  # Curl command
curl -X POST "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/reference-tables/uploads" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \
-d @- << EOF
{
  "data": {
    "attributes": {
      "headers": [
        ""
      ],
      "part_count": 3,
      "part_size": 10000000,
      "table_name": ""
    },
    "type": "upload"
  }
}
EOF

Create reference table

POST https://api.ap1.datadoghq.com/api/v2/reference-tables/tableshttps://api.ap2.datadoghq.com/api/v2/reference-tables/tableshttps://api.datadoghq.eu/api/v2/reference-tables/tableshttps://api.ddog-gov.com/api/v2/reference-tables/tableshttps://api.datadoghq.com/api/v2/reference-tables/tableshttps://api.us3.datadoghq.com/api/v2/reference-tables/tableshttps://api.us5.datadoghq.com/api/v2/reference-tables/tables

Overview

Create a new reference table. You can provide data in two ways: 1) Call POST api/v2/reference-tables/upload first to get an upload ID, then PUT chunks of CSV data to each provided URL, and finally call this POST endpoint with the upload_id in file_metadata, OR 2) Provide access_details in file_metadata pointing to a CSV file in cloud storage (Amazon S3, Azure Blob Storage, or GCP Cloud Storage).

Request

Body Data (required)

Expand All

Field

Type

Description

data

object

The definition of CreateTableRequestData object.

attributes

object

The definition of CreateTableRequestDataAttributes object.

description

string

The description of the reference table.

file_metadata

 <oneOf>

The definition of CreateTableRequestDataAttributesFileMetadata object.

Option 1

object

Cloud storage file metadata for create requests. Both access_details and sync_enabled are required.

access_details [required]

object

The definition of CreateTableRequestDataAttributesFileMetadataOneOfAccessDetails object.

aws_detail

object

The definition of CreateTableRequestDataAttributesFileMetadataOneOfAccessDetailsAwsDetail object.

aws_account_id [required]

string

The ID of the AWS account.

aws_bucket_name [required]

string

The name of the Amazon S3 bucket.

file_path [required]

string

The relative file path from the S3 bucket root to the CSV file.

azure_detail

object

The definition of CreateTableRequestDataAttributesFileMetadataOneOfAccessDetailsAzureDetail object.

azure_client_id [required]

string

The Azure client ID.

azure_container_name [required]

string

The name of the Azure container.

azure_storage_account_name [required]

string

The name of the Azure storage account.

azure_tenant_id [required]

string

The ID of the Azure tenant.

file_path [required]

string

The relative file path from the Azure container root to the CSV file.

gcp_detail

object

The definition of CreateTableRequestDataAttributesFileMetadataOneOfAccessDetailsGcpDetail object.

file_path [required]

string

The relative file path from the GCS bucket root to the CSV file.

gcp_bucket_name [required]

string

The name of the GCP bucket.

gcp_project_id [required]

string

The ID of the GCP project.

gcp_service_account_email [required]

string

The email of the GCP service account.

sync_enabled [required]

boolean

Whether this table is synced automatically.

Option 2

object

Local file metadata for create requests using the upload ID.

upload_id [required]

string

The upload ID.

schema [required]

object

The definition of CreateTableRequestDataAttributesSchema object.

fields [required]

[object]

The schema fields.

name [required]

string

The field name.

type [required]

enum

The field type for reference table schema fields. Allowed enum values: STRING,INT32

primary_keys [required]

[string]

List of field names that serve as primary keys for the table. Only one primary key is supported, and it is used as an ID to retrieve rows.

source [required]

enum

The source type for creating reference table data. Only these source types can be created through this API. Allowed enum values: LOCAL_FILE,S3,GCS,AZURE

table_name [required]

string

The name of the reference table.

tags

[string]

The tags of the reference table.

id

string

The ID of the reference table.

type [required]

enum

Reference table resource type. Allowed enum values: reference_table

default: reference_table

{
  "data": {
    "attributes": {
      "description": "string",
      "file_metadata": {
        "access_details": {
          "aws_detail": {
            "aws_account_id": "123456789000",
            "aws_bucket_name": "example-data-bucket",
            "file_path": "reference-tables/users.csv"
          },
          "azure_detail": {
            "azure_client_id": "aaaaaaaa-1111-2222-3333-bbbbbbbbbbbb",
            "azure_container_name": "reference-data",
            "azure_storage_account_name": "examplestorageaccount",
            "azure_tenant_id": "cccccccc-4444-5555-6666-dddddddddddd",
            "file_path": "tables/users.csv"
          },
          "gcp_detail": {
            "file_path": "data/reference_tables/users.csv",
            "gcp_bucket_name": "example-data-bucket",
            "gcp_project_id": "example-gcp-project-12345",
            "gcp_service_account_email": "example-service@example-gcp-project-12345.iam.gserviceaccount.com"
          }
        },
        "sync_enabled": false
      },
      "schema": {
        "fields": [
          {
            "name": "",
            "type": "STRING"
          }
        ],
        "primary_keys": [
          ""
        ]
      },
      "source": "LOCAL_FILE",
      "table_name": "",
      "tags": []
    },
    "id": "string",
    "type": "reference_table"
  }
}

Response

Created

The definition of TableResultV2 object.

Expand All

Field

Type

Description

data

object

The definition of TableResultV2Data object.

attributes

object

The definition of TableResultV2DataAttributes object.

created_by

string

UUID of the user who created the reference table.

description

string

The description of the reference table.

file_metadata

 <oneOf>

The definition of TableResultV2DataAttributesFileMetadata object.

Option 1

object

File metadata for reference tables created by cloud storage.

access_details

object

The definition of TableResultV2DataAttributesFileMetadataOneOfAccessDetails object.

aws_detail

object

The definition of TableResultV2DataAttributesFileMetadataOneOfAccessDetailsAwsDetail object.

aws_account_id

string

The ID of the AWS account.

aws_bucket_name

string

The name of the AWS bucket.

file_path

string

The relative file path from the S3 bucket root to the CSV file.

azure_detail

object

The definition of TableResultV2DataAttributesFileMetadataOneOfAccessDetailsAzureDetail object.

azure_client_id

string

The Azure client ID.

azure_container_name

string

The name of the Azure container.

azure_storage_account_name

string

The name of the Azure storage account.

azure_tenant_id

string

The ID of the Azure tenant.

file_path

string

The relative file path from the Azure container root to the CSV file.

gcp_detail

object

The definition of TableResultV2DataAttributesFileMetadataOneOfAccessDetailsGcpDetail object.

file_path

string

The relative file path from the GCS bucket root to the CSV file.

gcp_bucket_name

string

The name of the GCP bucket.

gcp_project_id

string

The ID of the GCP project.

gcp_service_account_email

string

The email of the GCP service account.

error_message

string

The error message returned from the sync.

error_row_count

int64

The number of rows that failed to sync.

error_type

enum

The type of error that occurred during file processing. This field provides high-level error categories for easier troubleshooting and is only present when there are errors. Allowed enum values: TABLE_SCHEMA_ERROR,FILE_FORMAT_ERROR,CONFIGURATION_ERROR,QUOTA_EXCEEDED,CONFLICT_ERROR,VALIDATION_ERROR,STATE_ERROR,OPERATION_ERROR,SYSTEM_ERROR

sync_enabled

boolean

Whether this table is synced automatically.

Option 2

object

File metadata for reference tables created by upload.

error_message

string

The error message returned from the creation/update.

error_row_count

int64

The number of rows that failed to create/update.

upload_id

string

The upload ID that was used to create/update the table.

last_updated_by

string

UUID of the user who last updated the reference table.

row_count

int64

The number of successfully processed rows in the reference table.

schema

object

The definition of TableResultV2DataAttributesSchema object.

fields [required]

[object]

The schema fields.

name [required]

string

The field name.

type [required]

enum

The field type for reference table schema fields. Allowed enum values: STRING,INT32

primary_keys [required]

[string]

List of field names that serve as primary keys for the table. Only one primary key is supported, and it is used as an ID to retrieve rows.

source

enum

The source type for reference table data. Includes all possible source types that can appear in responses. Allowed enum values: LOCAL_FILE,S3,GCS,AZURE,SERVICENOW,SALESFORCE,DATABRICKS,SNOWFLAKE

status

string

The status of the reference table.

table_name

string

The name of the reference table.

tags

[string]

The tags of the reference table.

updated_at

string

The timestamp of the last update to the reference table in ISO 8601 format.

id

string

The ID of the reference table.

type [required]

enum

Reference table resource type. Allowed enum values: reference_table

default: reference_table

{
  "data": {
    "attributes": {
      "created_by": "00000000-0000-0000-0000-000000000000",
      "description": "example description",
      "file_metadata": {
        "access_details": {},
        "upload_id": "00000000-0000-0000-0000-000000000000"
      },
      "last_updated_by": "",
      "row_count": 5,
      "schema": {
        "fields": [
          {
            "name": "id",
            "type": "INT32"
          },
          {
            "name": "name",
            "type": "STRING"
          }
        ],
        "primary_keys": [
          "id"
        ]
      },
      "source": "LOCAL_FILE",
      "status": "DONE",
      "table_name": "test_reference_table",
      "tags": [
        "tag1",
        "tag2"
      ],
      "updated_at": "2000-01-01T01:00:00+00:00"
    },
    "id": "00000000-0000-0000-0000-000000000000",
    "type": "reference_table"
  }
}

Bad Request

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Forbidden

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Too many requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example

                  # Curl command
curl -X POST "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/reference-tables/tables" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \
-d @- << EOF
{
  "data": {
    "attributes": {
      "file_metadata": {
        "access_details": {
          "aws_detail": {
            "aws_account_id": "123456789000",
            "aws_bucket_name": "example-data-bucket",
            "file_path": "reference-tables/users.csv"
          },
          "azure_detail": {
            "azure_client_id": "aaaaaaaa-1111-2222-3333-bbbbbbbbbbbb",
            "azure_container_name": "reference-data",
            "azure_storage_account_name": "examplestorageaccount",
            "azure_tenant_id": "cccccccc-4444-5555-6666-dddddddddddd",
            "file_path": "tables/users.csv"
          },
          "gcp_detail": {
            "file_path": "data/reference_tables/users.csv",
            "gcp_bucket_name": "example-data-bucket",
            "gcp_project_id": "example-gcp-project-12345",
            "gcp_service_account_email": "example-service@example-gcp-project-12345.iam.gserviceaccount.com"
          }
        }
      },
      "schema": {
        "fields": [
          {
            "name": "",
            "type": "STRING"
          }
        ],
        "primary_keys": [
          ""
        ]
      },
      "source": "LOCAL_FILE",
      "table_name": ""
    },
    "type": "reference_table"
  }
}
EOF

List tables

GET https://api.ap1.datadoghq.com/api/v2/reference-tables/tableshttps://api.ap2.datadoghq.com/api/v2/reference-tables/tableshttps://api.datadoghq.eu/api/v2/reference-tables/tableshttps://api.ddog-gov.com/api/v2/reference-tables/tableshttps://api.datadoghq.com/api/v2/reference-tables/tableshttps://api.us3.datadoghq.com/api/v2/reference-tables/tableshttps://api.us5.datadoghq.com/api/v2/reference-tables/tables

Overview

List all reference tables in this organization.

Arguments

Query Strings

Name

Type

Description

limit

integer

Number of tables to return.

offset

integer

Number of tables to skip for pagination.

sort

enum

Sort field and direction. Use field name for ascending, prefix with “-” for descending.
Allowed enum values: updated_at, table_name, status, -updated_at, -table_name, -status

filter[status]

string

Filter by table status.

filter[table_name][exact]

string

Filter by exact table name match.

filter[table_name][contains]

string

Filter by table name containing substring.

Response

OK

The definition of TableResultV2Array object.

Expand All

Field

Type

Description

data [required]

[object]

The reference tables.

attributes

object

The definition of TableResultV2DataAttributes object.

created_by

string

UUID of the user who created the reference table.

description

string

The description of the reference table.

file_metadata

 <oneOf>

The definition of TableResultV2DataAttributesFileMetadata object.

Option 1

object

File metadata for reference tables created by cloud storage.

access_details

object

The definition of TableResultV2DataAttributesFileMetadataOneOfAccessDetails object.

aws_detail

object

The definition of TableResultV2DataAttributesFileMetadataOneOfAccessDetailsAwsDetail object.

aws_account_id

string

The ID of the AWS account.

aws_bucket_name

string

The name of the AWS bucket.

file_path

string

The relative file path from the S3 bucket root to the CSV file.

azure_detail

object

The definition of TableResultV2DataAttributesFileMetadataOneOfAccessDetailsAzureDetail object.

azure_client_id

string

The Azure client ID.

azure_container_name

string

The name of the Azure container.

azure_storage_account_name

string

The name of the Azure storage account.

azure_tenant_id

string

The ID of the Azure tenant.

file_path

string

The relative file path from the Azure container root to the CSV file.

gcp_detail

object

The definition of TableResultV2DataAttributesFileMetadataOneOfAccessDetailsGcpDetail object.

file_path

string

The relative file path from the GCS bucket root to the CSV file.

gcp_bucket_name

string

The name of the GCP bucket.

gcp_project_id

string

The ID of the GCP project.

gcp_service_account_email

string

The email of the GCP service account.

error_message

string

The error message returned from the sync.

error_row_count

int64

The number of rows that failed to sync.

error_type

enum

The type of error that occurred during file processing. This field provides high-level error categories for easier troubleshooting and is only present when there are errors. Allowed enum values: TABLE_SCHEMA_ERROR,FILE_FORMAT_ERROR,CONFIGURATION_ERROR,QUOTA_EXCEEDED,CONFLICT_ERROR,VALIDATION_ERROR,STATE_ERROR,OPERATION_ERROR,SYSTEM_ERROR

sync_enabled

boolean

Whether this table is synced automatically.

Option 2

object

File metadata for reference tables created by upload.

error_message

string

The error message returned from the creation/update.

error_row_count

int64

The number of rows that failed to create/update.

upload_id

string

The upload ID that was used to create/update the table.

last_updated_by

string

UUID of the user who last updated the reference table.

row_count

int64

The number of successfully processed rows in the reference table.

schema

object

The definition of TableResultV2DataAttributesSchema object.

fields [required]

[object]

The schema fields.

name [required]

string

The field name.

type [required]

enum

The field type for reference table schema fields. Allowed enum values: STRING,INT32

primary_keys [required]

[string]

List of field names that serve as primary keys for the table. Only one primary key is supported, and it is used as an ID to retrieve rows.

source

enum

The source type for reference table data. Includes all possible source types that can appear in responses. Allowed enum values: LOCAL_FILE,S3,GCS,AZURE,SERVICENOW,SALESFORCE,DATABRICKS,SNOWFLAKE

status

string

The status of the reference table.

table_name

string

The name of the reference table.

tags

[string]

The tags of the reference table.

updated_at

string

The timestamp of the last update to the reference table in ISO 8601 format.

id

string

The ID of the reference table.

type [required]

enum

Reference table resource type. Allowed enum values: reference_table

default: reference_table

{
  "data": [
    {
      "attributes": {
        "created_by": "00000000-0000-0000-0000-000000000000",
        "description": "example description",
        "file_metadata": {
          "access_details": {},
          "error_message": "",
          "error_row_count": 0,
          "upload_id": "00000000-0000-0000-0000-000000000000"
        },
        "last_updated_by": "",
        "row_count": 5,
        "schema": {
          "fields": [
            {
              "name": "id",
              "type": "INT32"
            },
            {
              "name": "name",
              "type": "STRING"
            }
          ],
          "primary_keys": [
            "id"
          ]
        },
        "source": "LOCAL_FILE",
        "status": "DONE",
        "table_name": "test_reference_table",
        "tags": [
          "tag1",
          "tag2"
        ],
        "updated_at": "2000-01-01T01:00:00+00:00"
      },
      "id": "00000000-0000-0000-0000-000000000000",
      "type": "reference_table"
    },
    {
      "attributes": {
        "created_by": "00000000-0000-0000-0000-000000000000",
        "description": "example description",
        "file_metadata": {
          "access_details": {
            "aws_detail": {
              "aws_account_id": "test-account-id",
              "aws_bucket_name": "test-bucket",
              "file_path": "test_rt.csv"
            }
          },
          "error_message": "",
          "error_row_count": 0,
          "sync_enabled": true
        },
        "last_updated_by": "00000000-0000-0000-0000-000000000000",
        "row_count": 5,
        "schema": {
          "fields": [
            {
              "name": "location",
              "type": "STRING"
            },
            {
              "name": "file_name",
              "type": "STRING"
            }
          ],
          "primary_keys": [
            "location"
          ]
        },
        "source": "S3",
        "status": "DONE",
        "table_name": "test_reference_table_2",
        "tags": [
          "test_tag1",
          "tag2",
          "3"
        ],
        "updated_at": "2000-01-01T01:00:00+00:00"
      },
      "id": "00000000-0000-0000-0000-000000000000",
      "type": "reference_table"
    }
  ]
}

Forbidden

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Too many requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example

                  # Curl command
curl -X GET "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/reference-tables/tables" \
-H "Accept: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}"

Get table

GET https://api.ap1.datadoghq.com/api/v2/reference-tables/tables/{id}https://api.ap2.datadoghq.com/api/v2/reference-tables/tables/{id}https://api.datadoghq.eu/api/v2/reference-tables/tables/{id}https://api.ddog-gov.com/api/v2/reference-tables/tables/{id}https://api.datadoghq.com/api/v2/reference-tables/tables/{id}https://api.us3.datadoghq.com/api/v2/reference-tables/tables/{id}https://api.us5.datadoghq.com/api/v2/reference-tables/tables/{id}

Overview

Get a reference table by ID

Arguments

Path Parameters

Name

Type

Description

id [required]

string

The ID of the reference table to retrieve

Response

OK

The definition of TableResultV2 object.

Expand All

Field

Type

Description

data

object

The definition of TableResultV2Data object.

attributes

object

The definition of TableResultV2DataAttributes object.

created_by

string

UUID of the user who created the reference table.

description

string

The description of the reference table.

file_metadata

 <oneOf>

The definition of TableResultV2DataAttributesFileMetadata object.

Option 1

object

File metadata for reference tables created by cloud storage.

access_details

object

The definition of TableResultV2DataAttributesFileMetadataOneOfAccessDetails object.

aws_detail

object

The definition of TableResultV2DataAttributesFileMetadataOneOfAccessDetailsAwsDetail object.

aws_account_id

string

The ID of the AWS account.

aws_bucket_name

string

The name of the AWS bucket.

file_path

string

The relative file path from the S3 bucket root to the CSV file.

azure_detail

object

The definition of TableResultV2DataAttributesFileMetadataOneOfAccessDetailsAzureDetail object.

azure_client_id

string

The Azure client ID.

azure_container_name

string

The name of the Azure container.

azure_storage_account_name

string

The name of the Azure storage account.

azure_tenant_id

string

The ID of the Azure tenant.

file_path

string

The relative file path from the Azure container root to the CSV file.

gcp_detail

object

The definition of TableResultV2DataAttributesFileMetadataOneOfAccessDetailsGcpDetail object.

file_path

string

The relative file path from the GCS bucket root to the CSV file.

gcp_bucket_name

string

The name of the GCP bucket.

gcp_project_id

string

The ID of the GCP project.

gcp_service_account_email

string

The email of the GCP service account.

error_message

string

The error message returned from the sync.

error_row_count

int64

The number of rows that failed to sync.

error_type

enum

The type of error that occurred during file processing. This field provides high-level error categories for easier troubleshooting and is only present when there are errors. Allowed enum values: TABLE_SCHEMA_ERROR,FILE_FORMAT_ERROR,CONFIGURATION_ERROR,QUOTA_EXCEEDED,CONFLICT_ERROR,VALIDATION_ERROR,STATE_ERROR,OPERATION_ERROR,SYSTEM_ERROR

sync_enabled

boolean

Whether this table is synced automatically.

Option 2

object

File metadata for reference tables created by upload.

error_message

string

The error message returned from the creation/update.

error_row_count

int64

The number of rows that failed to create/update.

upload_id

string

The upload ID that was used to create/update the table.

last_updated_by

string

UUID of the user who last updated the reference table.

row_count

int64

The number of successfully processed rows in the reference table.

schema

object

The definition of TableResultV2DataAttributesSchema object.

fields [required]

[object]

The schema fields.

name [required]

string

The field name.

type [required]

enum

The field type for reference table schema fields. Allowed enum values: STRING,INT32

primary_keys [required]

[string]

List of field names that serve as primary keys for the table. Only one primary key is supported, and it is used as an ID to retrieve rows.

source

enum

The source type for reference table data. Includes all possible source types that can appear in responses. Allowed enum values: LOCAL_FILE,S3,GCS,AZURE,SERVICENOW,SALESFORCE,DATABRICKS,SNOWFLAKE

status

string

The status of the reference table.

table_name

string

The name of the reference table.

tags

[string]

The tags of the reference table.

updated_at

string

The timestamp of the last update to the reference table in ISO 8601 format.

id

string

The ID of the reference table.

type [required]

enum

Reference table resource type. Allowed enum values: reference_table

default: reference_table

{
  "data": {
    "attributes": {
      "created_by": "00000000-0000-0000-0000-000000000000",
      "description": "example description",
      "file_metadata": {
        "access_details": {},
        "upload_id": "00000000-0000-0000-0000-000000000000"
      },
      "last_updated_by": "",
      "row_count": 5,
      "schema": {
        "fields": [
          {
            "name": "id",
            "type": "INT32"
          },
          {
            "name": "name",
            "type": "STRING"
          }
        ],
        "primary_keys": [
          "id"
        ]
      },
      "source": "LOCAL_FILE",
      "status": "DONE",
      "table_name": "test_reference_table",
      "tags": [
        "tag1",
        "tag2"
      ],
      "updated_at": "2000-01-01T01:00:00+00:00"
    },
    "id": "00000000-0000-0000-0000-000000000000",
    "type": "reference_table"
  }
}

Forbidden

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Not Found

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Too many requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example

                  # Path parameters
export id="CHANGE_ME"
# Curl command
curl -X GET "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/reference-tables/tables/${id}" \
-H "Accept: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}"

Get rows by id

GET https://api.ap1.datadoghq.com/api/v2/reference-tables/tables/{id}/rowshttps://api.ap2.datadoghq.com/api/v2/reference-tables/tables/{id}/rowshttps://api.datadoghq.eu/api/v2/reference-tables/tables/{id}/rowshttps://api.ddog-gov.com/api/v2/reference-tables/tables/{id}/rowshttps://api.datadoghq.com/api/v2/reference-tables/tables/{id}/rowshttps://api.us3.datadoghq.com/api/v2/reference-tables/tables/{id}/rowshttps://api.us5.datadoghq.com/api/v2/reference-tables/tables/{id}/rows

Overview

Get reference table rows by their primary key values.

Arguments

Path Parameters

Name

Type

Description

id [required]

string

The ID of the reference table

Query Strings

Name

Type

Description

row_id [required]

array

List of row IDs (primary key values) to retrieve from the reference table.

Response

Some or all requested rows were found.

The definition of TableRowResourceArray object.

Expand All

Field

Type

Description

data [required]

[object]

The rows.

attributes

object

The definition of TableRowResourceDataAttributes object.

values

object

The values of the row.

id

string

The ID of the row.

type [required]

enum

Row resource type. Allowed enum values: row

default: row

{
  "data": [
    {
      "attributes": {
        "values": {}
      },
      "id": "string",
      "type": "row"
    }
  ]
}

Forbidden

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Not Found

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Too many requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example

                  # Path parameters
export id="table-123"
# Required query arguments
export row_id="[row1 row2]"
# Curl command
curl -X GET "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/reference-tables/tables/${id}/rows?row_id=${row_id}" \
-H "Accept: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}"

Update reference table

PATCH https://api.ap1.datadoghq.com/api/v2/reference-tables/tables/{id}https://api.ap2.datadoghq.com/api/v2/reference-tables/tables/{id}https://api.datadoghq.eu/api/v2/reference-tables/tables/{id}https://api.ddog-gov.com/api/v2/reference-tables/tables/{id}https://api.datadoghq.com/api/v2/reference-tables/tables/{id}https://api.us3.datadoghq.com/api/v2/reference-tables/tables/{id}https://api.us5.datadoghq.com/api/v2/reference-tables/tables/{id}

Overview

Update a reference table by ID. You can update the table’s data, description, and tags. Note: The source type cannot be changed after table creation. For data updates: For existing tables of type source:LOCAL_FILE, call POST api/v2/reference-tables/uploads first to get an upload ID, then PUT chunks of CSV data to each provided URL, and finally call this PATCH endpoint with the upload_id in file_metadata. For existing tables with source: types of S3, GCS, or AZURE, provide updated access_details in file_metadata pointing to a CSV file in the same type of cloud storage.

Arguments

Path Parameters

Name

Type

Description

id [required]

string

The ID of the reference table to update

Request

Body Data (required)

Expand All

Field

Type

Description

data

object

The definition of PatchTableRequestData object.

attributes

object

The definition of PatchTableRequestDataAttributes object.

description

string

The description of the reference table.

file_metadata

 <oneOf>

The definition of PatchTableRequestDataAttributesFileMetadata object.

Option 1

object

Cloud storage file metadata for patch requests. Allows partial updates of access_details and sync_enabled.

access_details

object

The definition of PatchTableRequestDataAttributesFileMetadataOneOfAccessDetails object.

aws_detail

object

The definition of PatchTableRequestDataAttributesFileMetadataOneOfAccessDetailsAwsDetail object.

aws_account_id

string

The ID of the AWS account.

aws_bucket_name

string

The name of the AWS bucket.

file_path

string

The relative file path from the S3 bucket root to the CSV file.

azure_detail

object

The definition of PatchTableRequestDataAttributesFileMetadataOneOfAccessDetailsAzureDetail object.

azure_client_id

string

The Azure client ID.

azure_container_name

string

The name of the Azure container.

azure_storage_account_name

string

The name of the Azure storage account.

azure_tenant_id

string

The ID of the Azure tenant.

file_path

string

The relative file path from the Azure container root to the CSV file.

gcp_detail

object

The definition of PatchTableRequestDataAttributesFileMetadataOneOfAccessDetailsGcpDetail object.

file_path

string

The relative file path from the GCS bucket root to the CSV file.

gcp_bucket_name

string

The name of the GCP bucket.

gcp_project_id

string

The ID of the GCP project.

gcp_service_account_email

string

The email of the GCP service account.

sync_enabled

boolean

Whether this table is synced automatically.

Option 2

object

Local file metadata for patch requests using upload ID.

upload_id [required]

string

The upload ID.

schema

object

The definition of PatchTableRequestDataAttributesSchema object.

fields [required]

[object]

The schema fields.

name [required]

string

The field name.

type [required]

enum

The field type for reference table schema fields. Allowed enum values: STRING,INT32

primary_keys [required]

[string]

List of field names that serve as primary keys for the table. Only one primary key is supported, and it is used as an ID to retrieve rows.

sync_enabled

boolean

Whether this table is synced automatically.

tags

[string]

The tags of the reference table.

id

string

The ID of the reference table.

type [required]

enum

Reference table resource type. Allowed enum values: reference_table

default: reference_table

{
  "data": {
    "attributes": {
      "description": "string",
      "file_metadata": {
        "access_details": {
          "aws_detail": {
            "aws_account_id": "123456789000",
            "aws_bucket_name": "example-data-bucket",
            "file_path": "reference-tables/users.csv"
          },
          "azure_detail": {
            "azure_client_id": "aaaaaaaa-1111-2222-3333-bbbbbbbbbbbb",
            "azure_container_name": "reference-data",
            "azure_storage_account_name": "examplestorageaccount",
            "azure_tenant_id": "cccccccc-4444-5555-6666-dddddddddddd",
            "file_path": "tables/users.csv"
          },
          "gcp_detail": {
            "file_path": "data/reference_tables/users.csv",
            "gcp_bucket_name": "example-data-bucket",
            "gcp_project_id": "example-gcp-project-12345",
            "gcp_service_account_email": "example-service@example-gcp-project-12345.iam.gserviceaccount.com"
          }
        },
        "sync_enabled": false
      },
      "schema": {
        "fields": [
          {
            "name": "",
            "type": "STRING"
          }
        ],
        "primary_keys": [
          ""
        ]
      },
      "sync_enabled": false,
      "tags": []
    },
    "id": "string",
    "type": "reference_table"
  }
}

Response

OK

Bad Request

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Forbidden

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Too many requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example

                  # Path parameters
export id="CHANGE_ME"
# Curl command
curl -X PATCH "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/reference-tables/tables/${id}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \
-d @- << EOF
{
  "data": {
    "attributes": {
      "schema": {
        "fields": [
          {
            "name": "",
            "type": "STRING"
          }
        ],
        "primary_keys": [
          ""
        ]
      }
    },
    "type": "reference_table"
  }
}
EOF

Delete table

DELETE https://api.ap1.datadoghq.com/api/v2/reference-tables/tables/{id}https://api.ap2.datadoghq.com/api/v2/reference-tables/tables/{id}https://api.datadoghq.eu/api/v2/reference-tables/tables/{id}https://api.ddog-gov.com/api/v2/reference-tables/tables/{id}https://api.datadoghq.com/api/v2/reference-tables/tables/{id}https://api.us3.datadoghq.com/api/v2/reference-tables/tables/{id}https://api.us5.datadoghq.com/api/v2/reference-tables/tables/{id}

Overview

Delete a reference table by ID

Arguments

Path Parameters

Name

Type

Description

id [required]

string

The ID of the reference table to delete

Response

OK

Forbidden

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Not Found

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Too many requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example

                  # Path parameters
export id="CHANGE_ME"
# Curl command
curl -X DELETE "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/reference-tables/tables/${id}" \
-H "Accept: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}"