Tables
Typed GTM datasets and the audit surface for row-level work.
A table is a typed dataset inside an organization. Rows hold GTM entities such as accounts, contacts, leads, signups, product events, or campaign state. Columns add behavior: enrichment, scoring, research, formulas, provider actions, and workflow links. Cells carry the output and provenance for each row.
Shape
| Field | Notes |
|---|---|
id | Stable table identifier |
name | Human-readable, unique within the project |
project | Optional project slug; defaults to general |
description | Free text |
columns | Ordered, typed; see Columns |
row_count | Maintained by the runtime |
web_url | Deep-link for visual inspection when returned by CLI/MCP |
Working with tables
oxygen tables list --json
oxygen tables create "Q1 TAM" \
--columns-json '[{"label":"Company Domain","key":"domain","data_type":"text","semantic_type":"company_domain"},{"label":"Company Name","key":"company_name","data_type":"text"}]' \
--json
oxygen tables describe <table-id> --json
oxygen tables preview <table-id> --limit 10 --json
oxygen tables query <table-id> --limit 10 --json
oxygen tables import <table-id> --file leads.csv --upsert-key domain --background --json
oxygen tables export <table-id> --format csv --output leads.csv --json
oxygen tables duplicate <table-id> --name "Q1 TAM (copy)" --json
oxygen tables rename <table-id> --name "Q1 TAM v2" --json
oxygen tables archive <table-id> --jsonWriting rows
oxygen tables insert <table-id> --rows-json '[{"domain":"acme.com"}]' --json
oxygen tables upsert <table-id> --key domain --rows-json '[{"domain":"acme.com","company_name":"Acme"}]' --jsonUse upsert for idempotent writes against a stable natural key. Larger summary upsert batches use Oxygen's bulk row engine; use tables import --background for file-backed or generated batches that should run durably in the worker.
Large file imports
In MCP, call oxygen_cli_file_import_prepare first so large files stay out of the assistant's context window. In a terminal:
oxygen tables import <table-id> --file leads.csv --background --json
oxygen tables import --create "From CSV" --file leads.csv --background --jsonTable-first rule
External writes mirror useful state back into the originating table. Provider record ids, sync status, errors, timestamps, run ids, and costs should be visible from cells and runs. The table is the audit log.
CSV, JSON, and XLSX files are import/export artifacts. Don't make them the durable state.