Alation

The Alation data catalog (data sources, schemas, tables, columns and full-text search) and its Document Hubs (folders and documents), through the Integration API under /integration/v1 and /integration/v2. Document create and update write; everything else reads. Verification level: unit.

Supported versions: The oldest Alation version toil supports hasn’t been established. toil needs the token APIs under integration/v1 and the Document Hub endpoints under integration/v2 (document, folder); releases with only Articles lack the latter. No release has been verified yet.

Credential

An Alation refresh token and the numeric user ID it belongs to: in Alation, your profile → Account Settings → Authentication → Create Refresh Token. Refresh tokens last 60 days by default. Alation’s screens don’t label the user ID: it is the number in the address of your profile page, such as 102 in https://alation.imagile.dev/user/102/.

toil never sends the refresh token to the data API. It POSTs it, with the user ID, to integration/v1/createAPIAccessToken/ on the connection’s own host, and sends the 24-hour API access token it gets back as the TOKEN header. The access token is kept in memory only, per connection, and renewed a minute before it expires; under toil mcp one exchange serves every call until then. There is no username, password or browser login.

Configuration

Environment variables (CI, or a one-off shell):

export TOIL_ALATION_BASE_URL=https://alation.imagile.dev
export TOIL_ALATION_REFRESH_TOKEN=<your refresh token>
export TOIL_ALATION_USER_ID=102

Or ~/.toil/config.json:

{
  "version": 2,
  "connections": {
    "corp-alation": { "area": "alation", "baseUrl": "https://alation.imagile.dev", "userId": 102 }
  },
  "defaults": { "alation": { "connection": "corp-alation" } }
}

The refresh token never goes in this file; a plaintext one there is refused with CONFIG_INVALID. Run toil connections add corp-alation --area alation (or toil connections login corp-alation for an existing connection) to keep it in the OS credential store, or set TOIL_ALATION_REFRESH_TOKEN. There’s no CI fallback variable.

A refused exchange is AUTH, naming the endpoint: check the refresh token and user ID, or make a new refresh token if it’s past its 60 days. Alation’s paths are Django routes, so every path keeps its trailing slash. A redirect to another host is refused, so the token stays on the configured one.

Commands

IDs are positional and must be positive integers. Lists return one page: --limit (default 100, 1 to 1000) and --offset (default 0, sent to Alation as skip), as { count, limit, skip, <items> }.

• token status: Mint an API access token from the configured refresh token and report its expiry (verifies credentials). It mints a new token each time, then validates it, and returns user_id, created_at, token_expires_at and token_status, never the token.
• datasource list: List data sources (--include-undeployed, --include-hidden), as { count, datasources }; not paged.
• datasource get: Get a data source by ID.
• schema list: List schemas, optionally within one data source (--ds, --name).
• schema get: Get a schema by ID.
• table list: List tables (descriptions, custom fields, fully-qualified keys): --ds, --schema, --schema-name, --name, and --search for a case-insensitive substring of the name.
• table get: Get a table by ID, optionally with its columns. --columns adds columnCount and columns, the first 1000 by ID, with an ALATION_COLUMNS_TRUNCATED warning when it reaches 1000.
• column list: List columns of a table (types, descriptions, keys, custom fields): --table, --table-name, --schema, --ds, --name, --search. At least one filter is required.
• column get: Get a column by ID.
• search: Full-text search across the catalog. --otype table,column restricts the object types (checked against Alation’s list), --limit (default 20, at most 10000) and --offset page it. Returns { query, total, limit, offset, fullSearchUrl, results }.
• folder list: List folders in a Document Hub (--hub, --parent, --search).
• folder get: Get a Document Hub folder by ID.
• document list: List documents in a Document Hub or folder (--hub, --folder, --parent-document, --search, --deleted).
• document get: Get a document by ID, including its custom field values.
• document schema: Print the --input-file JSON schema and an example for document create/update. With --example-only, data is the example itself, ready to save as an input file. It needs no connection.
• document create: Create a document (async: returns a job ID; check it with alation job get). Needs a title, --hub and --folder, from flags or --input-file.
• document update: Update a document (async: returns a job ID; custom field values replace existing values per field). It can’t change hubs, and needs at least one change.
• job get: Get the status of a bulk job (returned by document create/update).

get commands read the list endpoint with id=<n>&limit=1. If no row has that ID they return the first row anyway, with an ALATION_ID_MISMATCH warning in meta.warnings; check data.id.

Document input files

--input-file <path> (- reads stdin on the CLI) holds title, description, hub, folder, template, parentDocument, navLinkFolders, and fields: custom field values keyed by numeric field ID. Custom fields need a template. A string value starting with @ is read from that file, inside the workspace. Flags win over the file, and a meta.warnings entry names each value they overrode. Create and update return { jobId, document, overrides? }, where document is the payload sent.

toil alation search customer --otype table,column
toil alation table get 7 --columns
toil alation document schema --example-only > doc.json
toil alation document create --input-file doc.json --allow-write
toil alation job get 555