Creates a reference table. You can provide data in two ways:
Call POST /api/v2/reference-tables/upload to get an upload ID. Then, PUT the CSV data
(not the file itself) in chunks to each URL in the request body. Finally, call this
POST endpoint with upload_id in file_metadata.
Provide access_details in file_metadata pointing to a CSV file in cloud storage.
Attributes that define the reference table's configuration and properties.
description
string
Optional text describing the purpose or contents of this reference table.
file_metadata
<oneOf>
Metadata specifying where and how to access the reference table's data file.
Option 1
object
Cloud storage file metadata for create requests. Both access_details and sync_enabled are required.
access_details [required]
object
Cloud storage access configuration for the reference table data file.
aws_detail
object
Amazon Web Services S3 storage access configuration.
aws_account_id [required]
string
AWS account ID where the S3 bucket is located.
aws_bucket_name [required]
string
S3 bucket containing the CSV file.
file_path [required]
string
The relative file path from the S3 bucket root to the CSV file.
azure_detail
object
Azure Blob Storage access configuration.
azure_client_id [required]
string
Azure service principal (application) client ID with permissions to read from the container.
azure_container_name [required]
string
Azure Blob Storage container containing the CSV file.
azure_storage_account_name [required]
string
Azure storage account where the container is located.
azure_tenant_id [required]
string
Azure Active Directory tenant ID.
file_path [required]
string
The relative file path from the Azure container root to the CSV file.
gcp_detail
object
Google Cloud Platform storage access configuration.
file_path [required]
string
The relative file path from the GCS bucket root to the CSV file.
gcp_bucket_name [required]
string
GCP bucket containing the CSV file.
gcp_project_id [required]
string
GCP project ID where the bucket is located.
gcp_service_account_email [required]
string
Service account email with read permissions for the GCS bucket.
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
Schema defining the structure and columns of the reference table.
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
Name to identify this reference table.
tags
[string]
Tags for organizing and filtering reference tables.
A reference table resource containing its full configuration and state.
Expand All
Field
Type
Description
data
object
The data object containing the reference table configuration and state.
attributes
object
Attributes that define the reference table's configuration and properties.
created_by
string
UUID of the user who created the reference table.
description
string
Optional text describing the purpose or contents of this reference table.
file_metadata
object
Metadata specifying where and how to access the reference table's data file.
For cloud storage tables (S3/GCS/Azure):
sync_enabled and access_details will always be present
error fields (error_message, error_row_count, error_type) are present only when errors occur
For local file tables:
error fields (error_message, error_row_count) are present only when errors occur
sync_enabled, access_details are never present
access_details
object
Cloud storage access configuration. Only present for cloud storage sources (S3, GCS, Azure).
aws_detail
object
Amazon Web Services S3 storage access configuration.
aws_account_id
string
AWS account ID where the S3 bucket is located.
aws_bucket_name
string
S3 bucket containing the CSV file.
file_path
string
The relative file path from the S3 bucket root to the CSV file.
azure_detail
object
Azure Blob Storage access configuration.
azure_client_id
string
Azure service principal (application) client ID with permissions to read from the container.
azure_container_name
string
Azure Blob Storage container containing the CSV file.
azure_storage_account_name
string
Azure storage account where the container is located.
azure_tenant_id
string
Azure Active Directory tenant ID.
file_path
string
The relative file path from the Azure container root to the CSV file.
gcp_detail
object
Google Cloud Platform storage access configuration.
file_path
string
The relative file path from the GCS bucket root to the CSV file.
gcp_bucket_name
string
GCP bucket containing the CSV file.
gcp_project_id
string
GCP project ID where the bucket is located.
gcp_service_account_email
string
Service account email with read permissions for the GCS bucket.
error_message
string
The error message returned from the last operation (sync for cloud storage, upload for local file).
error_row_count
int64
The number of rows that failed to process.
error_type
enum
The type of error that occurred during file processing. Only applicable for cloud storage sources.
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 from cloud storage. Only applicable for cloud storage sources.
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
Schema defining the structure and columns of the reference table.
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 processing status of the table.
table_name
string
Unique name to identify this reference table. Used in enrichment processors and API calls.
tags
[string]
Tags for organizing and filtering reference tables.
updated_at
string
When the reference table was last updated, in ISO 8601 format.
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com"DD_API_KEY="<DD_API_KEY>"DD_APP_KEY="<DD_APP_KEY>"cargo run
/**
* Create reference table returns "Created" response
*/import{client,v2}from"@datadog/datadog-api-client";constconfiguration=client.createConfiguration();constapiInstance=newv2.ReferenceTablesApi(configuration);constparams: v2.ReferenceTablesApiCreateReferenceTableRequest={body:{data:{attributes:{fileMetadata:{accessDetails:{awsDetail:{awsAccountId:"123456789000",awsBucketName:"example-data-bucket",filePath:"reference-tables/users.csv",},azureDetail:{azureClientId:"aaaaaaaa-1111-2222-3333-bbbbbbbbbbbb",azureContainerName:"reference-data",azureStorageAccountName:"examplestorageaccount",azureTenantId:"cccccccc-4444-5555-6666-dddddddddddd",filePath:"tables/users.csv",},gcpDetail:{filePath:"data/reference_tables/users.csv",gcpBucketName:"example-data-bucket",gcpProjectId:"example-gcp-project-12345",gcpServiceAccountEmail:"example-service@example-gcp-project-12345.iam.gserviceaccount.com",},},syncEnabled: false,},schema:{fields:[{name:"field_1",type:"STRING",},],primaryKeys:["field_1"],},source:"LOCAL_FILE",tableName:"table_1",tags:["tag_1","tag_2"],},type:"reference_table",},},};apiInstance.createReferenceTable(params).then((data: v2.TableResultV2)=>{console.log("API called successfully. Returned data: "+JSON.stringify(data));}).catch((error: any)=>console.error(error));
