Connectors

A Connector connects ActQL to one external system. In a Program you only see names such as salesforce.accounts; authentication, paging, rate limits and the shape of each API stay inside the Connector. This page lists the Connectors that ship with ActQL, shows how a Connector is configured, and explains what every Connector page has in common.

Every Connector reads and writes, and all seventeen use the same model: typed sources that check validates, Effects and operations that are previewed and approved, and outcomes that are recorded and reconciled the same way whether the target is a warehouse table, a CRM record, a Slack channel or a bucket.

The ConnectorsCopy Anchor Link

Three things with similar namesCopy Anchor Link

• A Connector is the implementation: the code that knows how to talk to Salesforce or Snowflake.
• A connection is one configured instance of it: a name, an endpoint or account, and credentials. salesforce_prod and salesforce_sandbox are two connections of one Connector.
• A resource is something a connection exposes — an object, a table, a channel — and its SourceView is the typed, versioned contract for reading it: columns, types, key, paging.

How a Connector appears in a ProgramCopy Anchor Link

Every resource is a table-shaped source under the connection's name:

FROM salesforce.accounts AS a
JOIN snowflake.usage_30d AS u ON a.id = u.account_id
|> WHERE u.trend = 'down'

Columns and their types come from the Connector, so check validates a Program against them before anything is read.

Writes are Effects. Record Effects name the connection, the resource and the key:

|> EFFECT UPDATE salesforce.Account
     ID id SET (Churn_Risk__c = risk.value.level)

Operations — sending, posting, refreshing, starting a job — are Effects too, declared with EFFECT COMMAND and the operation's name:

FROM notifications
|> EFFECT COMMAND slack.post
     TARGET channel
     ID notification_id
     INPUT (text = message);

slack.post resolves to one versioned Command contract the Connector publishes: its input fields and types, the resource it acts on, the permission it needs, what its Preview shows and how its outcome is confirmed. Gmail's send, Tableau's refresh, Slack's post and a Drive upload all go through this one model, so every Effect — record write or operation — is previewed, decided and recorded the same way. See Effects and approvals.

Files and contentCopy Anchor Link

Four Connectors deal in files — Google Drive, Google Cloud Storage, Amazon S3 and Local files — and Snowflake, Salesforce, Notion, kintone, Slack, GitHub and Gmail expose file content as well. They all follow one set of rules:

Listing and reading are separate steps on purpose: a Program names the exact versions it reads, the byte limit applies to a known set of files, and a file replaced during the Run is a different version, never silently the same document. Working with files shows the Program side.

Connections and credentialsCopy Anchor Link

Connections live in the file actql.config.json points to as connectors (by default connectors.json). One entry per connection:

{
  "version": "actql-connectors/0.1",
  "connections": {
    "salesforce": {
      "connector": "salesforce",
      "instance_url": "https://acme.my.salesforce.com",
      "credentials": {"access_token": {"env": "SALESFORCE_ACCESS_TOKEN"}}
    },
    "snowflake": {
      "connector": "snowflake",
      "account": "acme-eu",
      "warehouse": "ANALYTICS",
      "database": "PRODUCT",
      "schema": "USAGE",
      "credentials": {"private_key": {"env": "SNOWFLAKE_PRIVATE_KEY"}}
    }
  }
}

Secrets are never written into the file. A credential field names an environment variable ({"env": "…"}) or a file ({"path": "…"}); the Host keeps the value and lends it to the Connector only for an operation policy has allowed. A Program cannot name a URL, a credential or a connection that is not configured. The Host turns this file into the Connector manifests it uses internally; you never write those by hand.

Two connections can use the same Connector under different names — a salesforce_prod and a salesforce_sandbox, for example — and a Program refers to whichever it needs.

Local and Cloud. On a Local Host you supply your own credentials. ActQL Cloud adds hosted OAuth for the Connectors whose providers require an approved application; where that approval is pending, the Cloud still accepts the same credential-based configuration as a Local Host. Each Connector page says what the account needs. Which Connectors run today is on Implementation status.

What catalog show tells youCopy Anchor Link

actql catalog show salesforce prints everything a Program can rely on for a connection, from the Catalog the Host has stored (catalog refresh asks the system again):

Connection  salesforce  (Salesforce, catalog revision 2026-10-14T09:12Z)

Sources
  accounts      key id        id string, name string, description string, industry string, …
  contacts      key id        id string, account_id string, email string, …

Effects
  Account       insert, update, upsert (External_Id__c), delete   preview full_diff
  Contact       insert, update, upsert, delete                    preview full_diff
  ContentVersion store                                            preview targeted

Operations
  convert_lead  TARGET Lead  INPUT (account_id string?, opportunity_name string?)
  send_email    INPUT (template string, to string)

Capabilities
  projection, filter (=, !=, <, >, IN, LIKE, IS NULL), order, limit

Permissions
  read:  accounts.read, contacts.read
  write: Account.update, Account.create, …

An agent writes Programs against this, not against guesses.

The mock profileCopy Anchor Link

--profile mock (CLI) or profile: 'mock' (SDK) replaces every connection with a mock that serves the records in mock.data and applies writes to those records, so a Program can create a record and read it back without credentials. The quickstart runs the churn-risk Program this way.

The switch to real connections is a change of configuration, not of the Program: as long as the source names, columns, keys, Mappings and operations mean the same in the mock and the real system, the Program runs unchanged. Where the real system differs — a renamed field, a missing object — check reports the difference; nothing runs under a quietly different interpretation.

Capabilities and pushdownCopy Anchor Link

Each Connector declares what its system can compute itself — which columns can be selected at the source, which filters it can apply, whether it can aggregate, sort or join — and under which conditions the result keeps ActQL's meaning exactly (NULL handling, collation, numeric precision). The planner runs work inside the source only under those conditions and runs the rest in the engine; explain shows where each step went. A Capability is never a permission: at every protected boundary — a read, data leaving for a model, an Effect — the Host checks that the operation is allowed. See Plans and pushdown.

What every Connector page coversCopy Anchor Link

Need a system that is not listed? Building a Connector explains what a Connector declares and how to write one.