PermuteDocs
Go to Permute

Query and analyze

Discover sources and inspect tables

Find permitted sources, check data availability, and inspect table and column names before writing a query.

Workflow

  1. 1Use a workspace client with Read access to the sources you need. List sources and keep their returned IDs.
  2. 2Choose a source and inspect its availability. A saved connection or completed setup does not prove that data is ready.
  3. 3List tables without loading every column, then describe the selected table using its returned ID.
  4. 4Use the returned table names, fields, and provider when writing SQL. Keep availability and result limits visible to users.

Example

typescript
import { PermuteClient } from '@permute/sdk';

const client = new PermuteClient({
  apiKey: process.env.PERMUTE_API_KEY!,
}).withWorkspace(process.env.PERMUTE_WORKSPACE_ID!);

const sources = await client.sources.list();
console.table(sources.items.map((source) => ({
  id: source.id, name: source.name, type: source.type,
  availability: source.availability.status,
})));

// Choose an ID from the list, then rerun with PERMUTE_SOURCE_ID set.
const sourceId = process.env.PERMUTE_SOURCE_ID;
if (!sourceId) throw new Error('Set PERMUTE_SOURCE_ID to a source returned above');
const source = sources.items.find((item) => item.id === sourceId);
if (!source) throw new Error('Choose a source returned by this workspace');
console.log('Availability:', source.availability);
if (source.availability.status !== 'ready') {
  throw new Error('Review source availability before using its data');
}

const tables = await client.sources.listTables(sourceId);
console.table(tables);
const tableId = process.env.PERMUTE_TABLE_ID;
if (!tableId) throw new Error('Set PERMUTE_TABLE_ID to a table ID returned above');
const table = await client.sources.describeTable(sourceId, tableId);
console.log('SQL table name:', table.name);
console.table(table.fields);

Check availability and freshness

StatusWhat to check
readyThe source is available. Check the last successful time when supplied.
refreshingA refresh is running; an earlier successful result may remain available.
degradedAn earlier result may remain available after a refresh problem. Review the reason and age.
preparingThe source is not yet ready for queries. Check processing, sync, or publication.
failedInspect the reported failure before relying on the source.

The example stops unless the source is ready. Some sources remain readable during a refresh or after a failure (the refreshing and degraded states), so check the age of their data. Inspect availability.reason and lastSuccessfulAt when provided, and show any limitation alongside the result.

For imported files and synced connectors, allow processing or the first sync to finish. Operation outputs need a successful run, and managed databases need a published schema. A source’s saved instructions describe its intended behavior; they do not verify its results or freshness.

Understand an empty source list

An empty list means this caller can discover no queryable sources in the selected workspace. Confirm the workspace and resource grants before adding or reconnecting anything. API keys need their own grants; hosted app reads require both app and viewer access.

If the workspace has no data, connect a provider or upload a dataset. If a source exists but has no tables yet, check its readiness and schema rather than inventing table names. Table, row, or column grants within a shared source do not authorize current source queries.