Discover Tables and Columns

Discover the Workspace catalog before assuming that a Provider, stream, artifact, Parable, or Plot exists. SQL clients can use standard Flight SQL metadata; Workspace API clients can request the richer semantic catalog.

Use Flight SQL metadata

The TypeScript Flight SQL client returns Arrow IPC for each metadata request:

import { tableFromIPC } from "apache-arrow";

const catalogs = tableFromIPC(await client.getCatalogs());
const providerSchemas = tableFromIPC(
  await client.getSchemas({ catalog: "providers" }),
);
const googleTables = tableFromIPC(
  await client.getTables({
    catalog: "providers",
    schema: "google",
    includeSchema: true,
  }),
);

console.log(catalogs.toArray());
console.log(providerSchemas.toArray());
console.log(googleTables.toArray());

The equivalent standard Flight SQL operations are:

Operation	Use it to
`GetCatalogs`	List pools and companion catalogs.
`GetDbSchemas`	List schemas inside a catalog.
`GetTables`	List tables and optionally include each Arrow schema.
`GetTableTypes`	Discover advertised table kinds.
`GetPrimaryKeys`	Read a table’s logical primary key.
`GetImportedKeys`	Read foreign keys imported by a table.
`GetExportedKeys`	Find tables that reference a table.
`GetCrossReference`	Inspect one table-to-table relationship.

Use the semantic catalog

The semantic catalog exposes the same logical tables through the Workspace API, with Parable-specific ownership and annotations. Use the SDK for your language:

const catalog = await sdk.catalogV2.catalog();

catalog = sdk.catalog_v2.catalog()

catalog, err := sdk.CatalogV2Namespace.Catalog(ctx)

let catalog = sdk.catalog_v2.catalog(None).await?;

Use Flight SQL metadata when a generic SQL or BI client needs structural discovery. Use the semantic catalog when an application needs Provider annotations, table kinds, source versions, or semantic scalar names.

Check whether a table has rows

A declared table may be empty. Once discovery confirms its name, check it with a bounded query:

SELECT COUNT(*) AS row_count
FROM providers.google.users

An empty result is different from a missing table: empty tables still have a discoverable schema.

​Use Flight SQL metadata

​Use the semantic catalog

​Check whether a table has rows

Use Flight SQL metadata

Use the semantic catalog

Check whether a table has rows