Datasets

Datasets are logical containers that group related tables together. They help organize your data by domain, project, or use case.

Data Hierarchy

Click to expand

• Team: The organizational boundary (billing, access control)
• Dataset: Groups related tables (e.g., “Sales Data”, “Customer Analytics”)
• Table: Contains data with a defined schema
• Rows: Individual records within a table

Creating a Dataset

Create a dataset

cURL

curl -X POST https://api.catalyzed.ai/datasets \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "teamId": "ZkoDMyjZZsXo4VAO_nJLk",
    "name": "Sales Analytics",
    "description": "Sales data for analytics and reporting"
  }'

TypeScript

const response = await fetch("https://api.catalyzed.ai/datasets", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    teamId: "ZkoDMyjZZsXo4VAO_nJLk",
    name: "Sales Analytics",
    description: "Sales data for analytics and reporting",
  }),
});
const dataset = await response.json();

Python

response = requests.post(
    "https://api.catalyzed.ai/datasets",
    headers={"Authorization": f"Bearer {api_token}"},
    json={
        "teamId": "ZkoDMyjZZsXo4VAO_nJLk",
        "name": "Sales Analytics",
        "description": "Sales data for analytics and reporting"
    }
)
dataset = response.json()

Response:

{
  "datasetId": "HoIEJNIPiQIy6TjVRxjwz",
  "teamId": "ZkoDMyjZZsXo4VAO_nJLk",
  "name": "Sales Analytics",
  "description": "Sales data for analytics and reporting",
  "tags": [],
  "metadata": {},
  "managed": false,
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Listing Datasets

List datasets in a team

cURL

curl "https://api.catalyzed.ai/datasets?teamIds=ZkoDMyjZZsXo4VAO_nJLk" \
  -H "Authorization: Bearer $API_TOKEN"

TypeScript

const response = await fetch(
  "https://api.catalyzed.ai/datasets?teamIds=ZkoDMyjZZsXo4VAO_nJLk",
  { headers: { Authorization: `Bearer ${apiToken}` } }
);
const { datasets } = await response.json();

Python

response = requests.get(
    "https://api.catalyzed.ai/datasets",
    params={"teamIds": "ZkoDMyjZZsXo4VAO_nJLk"},
    headers={"Authorization": f"Bearer {api_token}"}
)
datasets = response.json()["datasets"]

Query Parameters

The list endpoint supports filtering, pagination, and sorting:

Parameter	Type	Description
teamIds	string	Comma-separated team IDs to filter by
datasetIds	string	Comma-separated dataset IDs to filter by
name	string	Filter by name (partial match)
tags	string	Comma-separated tags to filter by
managed	boolean	Filter by managed status (true or false)
page	number	Page number (starts at 1, default: 1)
pageSize	number	Results per page (1-100, default: 20)
orderBy	string	Sort by: createdAt, name, updatedAt, description
orderDirection	string	Sort direction: asc or desc

curl "https://api.catalyzed.ai/datasets?teamIds=ZkoDMyjZZsXo4VAO_nJLk&page=1&pageSize=10&orderBy=name&orderDirection=asc" \
  -H "Authorization: Bearer $API_TOKEN"

Getting a Dataset

Get dataset by ID

cURL

curl https://api.catalyzed.ai/datasets/HoIEJNIPiQIy6TjVRxjwz \
  -H "Authorization: Bearer $API_TOKEN"

TypeScript

const response = await fetch("https://api.catalyzed.ai/datasets/HoIEJNIPiQIy6TjVRxjwz", {
  headers: { Authorization: `Bearer ${apiToken}` },
});
const dataset = await response.json();

Python

response = requests.get(
    "https://api.catalyzed.ai/datasets/HoIEJNIPiQIy6TjVRxjwz",
    headers={"Authorization": f"Bearer {api_token}"}
)
dataset = response.json()

Updating a Dataset

Update dataset

cURL

curl -X PUT https://api.catalyzed.ai/datasets/HoIEJNIPiQIy6TjVRxjwz \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Analytics v2",
    "description": "Updated sales data with 2024 metrics"
  }'

TypeScript

await fetch("https://api.catalyzed.ai/datasets/HoIEJNIPiQIy6TjVRxjwz", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${apiToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Sales Analytics v2",
    description: "Updated sales data with 2024 metrics",
  }),
});

Python

requests.put(
    "https://api.catalyzed.ai/datasets/HoIEJNIPiQIy6TjVRxjwz",
    headers={"Authorization": f"Bearer {api_token}"},
    json={
        "name": "Sales Analytics v2",
        "description": "Updated sales data with 2024 metrics"
    }
)

Deleting a Dataset

Caution

Deleting a dataset also deletes all tables within it. This action cannot be undone.

Delete dataset

cURL

curl -X DELETE https://api.catalyzed.ai/datasets/HoIEJNIPiQIy6TjVRxjwz \
  -H "Authorization: Bearer $API_TOKEN"

TypeScript

await fetch("https://api.catalyzed.ai/datasets/HoIEJNIPiQIy6TjVRxjwz", {
  method: "DELETE",
  headers: { Authorization: `Bearer ${apiToken}` },
});

Python

requests.delete(
    "https://api.catalyzed.ai/datasets/HoIEJNIPiQIy6TjVRxjwz",
    headers={"Authorization": f"Bearer {api_token}"}
)

Dataset Properties

Field	Type	Description
datasetId	string	Unique identifier
teamId	string	Team that owns this dataset
name	string	Human-readable name (1-255 characters)
description	string | null	Description (nullable)
tags	string[]	Tags for organization (defaults to [])
metadata	object	Custom key-value metadata (defaults to {})
managed	boolean	Whether the dataset is system-managed
createdAt	string	ISO 8601 timestamp of creation
updatedAt	string	ISO 8601 timestamp of last modification

Working with Tables

Once you have a dataset, you can create tables within it. See Tables for details on:

• Defining table schemas
• Inserting and querying data
• Managing indexes
• Schema migrations

Use Cases

Organizing by Domain

Group tables by business domain to keep related data together. This approach works well when different teams or functions own distinct data areas.

Click to expand

Organizing by Environment

Separate datasets by environment to isolate production data from development and staging. Each environment contains the same table structure, making it easy to promote changes through your deployment pipeline.

Click to expand

API Reference

• List datasets
• Create dataset
• Get dataset by ID
• Update dataset
• Delete dataset