Workflow
- 1Use a workspace client with Read access to the sources you need. List sources and keep their returned IDs.
- 2Choose a source and inspect its availability. A saved connection or completed setup does not prove that data is ready.
- 3List tables without loading every column, then describe the selected table using its returned ID.
- 4Use the returned table names, fields, and provider when writing SQL. Keep availability and result limits visible to users.
Example
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
| Status | What to check |
|---|---|
| ready | The source is available. Check the last successful time when supplied. |
| refreshing | A refresh is running; an earlier successful result may remain available. |
| degraded | An earlier result may remain available after a refresh problem. Review the reason and age. |
| preparing | The source is not yet ready for queries. Check processing, sync, or publication. |
| failed | Inspect 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.