インストール

ActQLを使うと、CRM、データウェアハウス、ファイル、SaaSのAPIといった、つないだシステム全体を1つのデータベースのように扱えます。SQLで読んで結合し、書き戻すときは、適用する前に内容を確認できるEffectを通します。

ActQLは、コマンドラインツール、TypeScript/Nodeのライブラリ、Pythonのライブラリの3つの形で提供されます。動いているエンジンはどれも同じです。プログラムをどこで動かしたいかに合わせて選んでください。このページでは、それぞれを手元のマシンに入れる手順と、ActQLが状態をどこに保存するかを説明します。

必要なものCopy Anchor Link

エンジン本体と、手元で大きめのJOINを実行するためのDuckDBは同梱されているので、ほかにインストールするものはなく、動かしておくサーバーも、アカウントを作る必要もありません。外部システムのConnectorに認証情報が必要になるのは、本物のシステムへの接続を設定するときだけです。クイックスタートで使うmockプロファイルには、認証情報は要りません。

CLICopy Anchor Link

npm install -g actql
actql version

さっそくクエリを投げてみます。

$ actql sql "SELECT 1 AS id, 'hello' AS greeting"
id  greeting
--  --------
1   hello

actql sql は読み取り専用のクエリを実行して、結果を表示します。書き込みを含むプログラムは actql run で実行し、必要なら承認のために止まります。プログラムの検査、Checkpointの承認、Runの追跡、Connectorで使えるテーブルの確認など、ほかのコマンドはCLIリファレンスにまとめています。

TypeScriptとNodeCopy Anchor Link

npm install @actql/node

@actql/node は、エンジンをあなたのアプリに組み込みます。リモートのHostにつなぐクライアントも含まれているので、接続オプションを変えるだけで、同じコードがサーバーやActQL Cloudにも届きます。TypeScriptとNodeを参照してください。

open() が返すのは、データベースと同じ感覚でクエリを投げられるハンドルです。例で db という名前にしているのはそのためです。このハンドルは読み取り専用で、書き込みを含むプログラムには connect() で作る完全なクライアントを使います。

import {open} from '@actql/node';

const db = await open({stateDir: '.actql'});
try {
  console.log(await db.sql('SELECT 1 AS id').all()); // [ { id: 1 } ]
} finally {
  await db.close();
}

PythonCopy Anchor Link

uv add actql
# or
pip install actql

import actql

with actql.open(state_dir=".actql") as db:
    print(db.sql("SELECT 1 AS id").all())  # [{'id': 1}]

Pythonを参照してください。

リモートのHostやActQL Cloudを呼ぶだけの場合Copy Anchor Link

他の誰かが運用するHost（リモートのHostやActQL Cloud）を呼ぶだけのアプリケーションには、エンジンは要りません。代わりに軽量なSDKを入れます。同じクライアントAPIで、mode: 'remote' だけがあり、ローカルのモードはありません。

npm install @actql/sdk      # TypeScript
uv add actql-sdk            # Python（または pip install actql-sdk）

上の標準パッケージにもリモート用のクライアントが入っているので、ローカルで始めたアプリケーションは接続のオプションを変えるだけでリモートに切り替えられます。ローカルとリモートのHostを参照してください。

コーディングエージェント向けのスキルCopy Anchor Link

コーディングエージェントにプログラムを書かせるなら、ActQLのスキルを渡してください。言語、CLI、レビューの流れをエージェントに教えるものです。

npx skills add actql/skills

そのうえで、エージェントに「Start ActQL setup」と頼みます。スキルはプログラムを書くガイドとCLIリファレンスを参照しています。

状態はどこに保存されるかCopy Anchor Link

どの使い方でも、永続的な状態（Run、取り込んだ観測、Checkpoint、Result）は1つのディレクトリに保存されます。CLIは actql.config.json の state_dir（既定は ./.actql）を使い、ライブラリは installation.directory または stateDir で場所を受け取ります。このディレクトリはバージョン管理に入れず、データベースと同じようにバックアップしてください。クラッシュのあとにRunを再開できるのも、status が読むのも、このディレクトリです。

次に読むCopy Anchor Link

• クイックスタート：解約リスクのプログラムをmockのシステムに対して実行し、Checkpointを承認して、結果を読む
• ローカルとリモートのHost：本物のシステムに対する接続、認証情報、ポリシー