Connector

Connectorは、ActQLを1つの外部システムにつなぎます。プログラムから見えるのは salesforce.accounts のような名前だけで、認証、ページング、レート制限、各APIの形はConnectorの中に収まります。このページでは、ActQLに同梱されるConnectorの一覧、Connectorの設定のしかた、そして各Connectorのページに共通する内容を説明します。

どのConnectorも読み取りと書き込みの両方に対応し、17種類すべてが同じモデルで動きます。check が検証する型付きの読み取り元、プレビューと承認を通るEffectと操作、そして記録され突き合わせられる結果です。対象がDWHのテーブルでも、CRMのレコードでも、Slackのチャンネルでも、バケットでも変わりません。

Connectorの一覧Copy Anchor Link

似た名前の3つのものCopy Anchor Link

• Connectorは実装です。SalesforceやSnowflakeと話す方法を知っているコードです。
• **接続（connection）**は、その設定済みのインスタンス1つです。名前、接続先やアカウント、認証情報を持ちます。salesforce_prod と salesforce_sandbox は、1つのConnectorの2つの接続です。
• リソースは、接続が公開するもの（オブジェクト、テーブル、チャンネル）です。そのSourceViewは、それを読むための型付きでバージョン付きの契約で、列、型、キー、ページングを定めます。

プログラムの中でのConnectorの見え方Copy Anchor Link

どのリソースも、接続名の下にあるテーブル形の読み取り元です。

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

列とその型はConnectorから来るので、check は何かを読む前に、それらに照らしてプログラムを検証します。

書き込みはEffectです。レコードのEffectは、接続、リソース、キーを指定します。

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

送信、投稿、更新処理の開始、ジョブの起動といった操作もEffectです。EFFECT COMMAND と操作の名前で宣言します。

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

slack.post は、Connectorが公開するバージョン付きのCommand契約1つに解決されます。入力の項目と型、対象となるリソース、必要な権限、プレビューに出る内容、結果の確認方法です。Gmailの send、Tableauの refresh、Slackの post、Driveへのアップロードは、すべてこの1つのモデルを通ります。レコードの書き込みも操作も、同じようにプレビューされ、判断され、記録されます。Effectと承認を参照してください。

ファイルとコンテンツCopy Anchor Link

Google Drive、Google Cloud Storage、Amazon S3、ローカルファイルの4つはファイルを扱うConnectorで、Snowflake、Salesforce、Notion、kintone、Slack、GitHub、Gmailもファイルの内容を公開します。どれも同じ規則に従います。

一覧と読み取りを分けているのには理由があります。プログラムが読むバージョンを正確に指定でき、バイト数の上限が決まったファイルの集合に適用され、Runの途中で置き換えられたファイルは別のバージョンとして扱われ、黙って同じ文書になることがないからです。プログラム側の書き方はファイルを扱うにあります。

接続と認証情報Copy Anchor Link

接続は、actql.config.json が connectors として指すファイル（既定は connectors.json）に書きます。接続ごとに1エントリです。

{
  "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"}}
    }
  }
}

秘密情報をファイルに書くことはありません。認証情報の項目には、環境変数（{"env": "…"}）かファイル（{"path": "…"}）を指定します。Hostが値を保持し、ポリシーが許可した操作のときだけConnectorに貸し出します。プログラムから、設定にないURL、認証情報、接続を指定することはできません。Hostはこのファイルを内部で使うConnectorのマニフェストに変換します。マニフェストを手で書くことはありません。

同じConnectorを別の名前で2つの接続にできます。たとえば salesforce_prod と salesforce_sandbox で、プログラムは必要なほうを参照します。

ローカルとCloud。 ローカルのHostでは、自分の認証情報を用意して使います。ActQL Cloudは、プロバイダーが承認済みアプリを求めるConnectorについて、ホスト型のOAuthを追加します。その承認が済んでいないあいだも、CloudはローカルのHostと同じ認証情報ベースの設定を受け付けます。アカウントに何が必要かは、各Connectorのページにあります。今日動くConnectorは実装状況にあります。

catalog show が教えてくれることCopy Anchor Link

actql catalog show salesforce は、Hostが保存しているCatalogから、その接続についてプログラムが頼りにできるものをすべて表示します（catalog refresh はシステムに問い合わせ直します）。

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, …

エージェントは推測ではなく、これを見てプログラムを書きます。

mockプロファイルCopy Anchor Link

--profile mock（CLI）または profile: 'mock'（SDK）は、すべての接続をmockに置き換えます。mockは mock.data のレコードを返し、書き込みをそのレコードに反映するので、認証情報なしでレコードを作って読み返すところまで試せます。クイックスタートは、解約リスクのプログラムをこの方法で動かします。

本物の接続への切り替えは設定の変更であって、プログラムの変更ではありません。読み取り元の名前、列、キー、Mapping、操作がmockと本物で同じ意味を持つかぎり、プログラムはそのまま動きます。本物のシステムが違っていれば（項目名が変わっている、オブジェクトがない）、check がその差分を報告します。黙って別の解釈で動くことはありません。

CapabilityとプッシュダウンCopy Anchor Link

各Connectorは、そのシステム自身が計算できること（読み取り元で選べる列、適用できる絞り込み、集計・並べ替え・JOINができるか）と、その結果がActQLの意味を正確に保つ条件（NULLの扱い、照合順序、数値の精度）を宣言します。プランナーはその条件のもとでだけ処理をシステムの中で実行し、残りはエンジンで実行します。各ステップがどこに行ったかは explain が示します。Capabilityは権限ではありません。保護された境界（読み取り、LLMへのデータ送信、Effect）のそれぞれで、Hostはその操作が許可されているかを確認します。Planとプッシュダウンを参照してください。

各ConnectorのページにあるものCopy Anchor Link

一覧にないシステムをつなぎたいときは、Connectorを作るで、Connectorが何を宣言し、どう書くかを説明しています。