メインコンテンツへスキップ
AI 関数は ClickHouse の組み込み関数で、AI の呼び出しや埋め込みの生成に使用でき、データの処理、情報の抽出、データの分類などを行えます。
AI 関数は予測不能な出力を返す場合があります。結果は、プロンプトの品質と使用するモデルに大きく依存します。
すべての関数は、以下を提供する共通のインフラストラクチャを利用しています。

​
設定

AI 関数は、プロバイダーの認証情報と設定を格納する named collection を参照します。各関数の最初の引数は、この collection の名前です。 プロバイダーの認証情報を含む named collection を作成するステートメントの例: 
CREATE NAMED COLLECTION ai_credentials AS
    provider = 'openai',
    endpoint = 'https://api.openai.com/v1/chat/completions',
    model = 'gpt-4o-mini',
    api_key = 'sk-...';

​
名前付きコレクションのパラメータ

パラメータ型デフォルト説明
providerString—モデルプロバイダー。サポート対象: 'openai', 'anthropic'。以下の注記を参照してください。
endpointString—API エンドポイント URL。
modelString—モデル名 (例: 'gpt-4o-mini', 'text-embedding-3-small') 。
api_keyString—プロバイダーの認証用キー。
max_tokensUInt641024API 呼び出しごとの出力トークン数の上限。
api_versionString—API バージョン文字列。Anthropic で使用されます ('2023-06-01') 。
provider = 'openai' を設定し、endpoint を利用するサービスに向けることで、任意の OpenAI 互換 API (例: vLLM、Ollama、LiteLLM) を使用できます。

​
クエリレベルの設定

AI 関連の設定はすべて、ai_function_ プレフィックスで Settings に一覧表示されています。

​
エンドポイントホストの制限

AI named collection の endpoint URL は、サーバーが自身の identity で接続する送信先であり、リクエストヘッダーに named collection の api_key を含めて送信します。デフォルトでは、ClickHouse はすべてのホストへの接続を許可します。関数を特定の provider 群のみに制限するには、サーバー設定で remote_url_allow_hosts を設定します。例: 
<remote_url_allow_hosts>
    <host>api.openai.com</host>
    <host>api.anthropic.com</host>
</remote_url_allow_hosts>
この設定はサーバー全体に適用され、HTTP を使用するすべての機能に適用されることに注意してください。

​
サポートされているプロバイダー

プロバイダーprovider の値チャット関数注記
OpenAI'openai'はいデフォルトのプロバイダーです。
Anthropic'anthropic'はい/v1/messages endpoint を使用します。

​
オブザーバビリティ

AI 関数のアクティビティは、ClickHouse の ProfileEvents で追跡できます。
ProfileEventDescription
AIAPICallsAI provider に送信された HTTP リクエスト数。
AIInputTokens消費された入力トークンの合計数。
AIOutputTokens消費された出力トークンの合計数。
AIRowsProcessed結果が返された行数。
AIRowsSkippedスキップされた行数 (クォータ超過、または ai_function_throw_on_error = 0 の場合のエラー) 。
これらのイベントをクエリします。 
SELECT
    ProfileEvents['AIAPICalls'] AS api_calls,
    ProfileEvents['AIInputTokens'] AS input_tokens,
    ProfileEvents['AIOutputTokens'] AS output_tokens
FROM system.query_log
WHERE query_id = 'query_id'
AND type = 'QueryFinish'
ORDER BY event_time DESC;

​
aiClassify

導入バージョン: v26.4.0 指定されたテキストを、LLMプロバイダーを使用して、与えられたカテゴリのいずれか 1 つに分類します。 この関数は、固定の分類プロンプトと、モデルが指定されたラベルのうちちょうど 1 つだけを返すよう制約する JSON スキーマのレスポンスフォーマットとともに、テキストを送信します。レスポンスが {"category": "..."} 形式の JSON オブジェクトとして返された場合は、ラベルが取り出され、その文字列が返されます。 最初の引数は、プロバイダー、モデル、エンドポイント、APIキーを指定する named collection です。 構文 
aiClassify(collection, text, categories[, temperature])
別名: AIClassify 引数
  • collection — provider credentials と設定を含む named collection の名前。String
  • text — 分類するテキスト。String
  • categories — 候補となるカテゴリラベルの定数リスト。Array(String)
  • temperature — ランダム性を制御するサンプリング温度。デフォルト: 0.0。Float64
戻り値 指定されたカテゴリラベルのいずれか、またはリクエストが失敗し、ai_function_throw_on_error が無効になっている場合はカラム型のデフォルト値 (空文字列) 。String 例 感情を分類
Query
SELECT aiClassify('ai_credentials', 'I love this product!', ['positive', 'negative', 'neutral'])
Response
positive
カラムを分類する
Query
SELECT body, aiClassify('ai_credentials', body, ['bug', 'question', 'feature']) AS kind FROM issues LIMIT 5
Response

​
aiExtract

導入バージョン: v26.4.0 LLMプロバイダーを使用して、非構造化テキストから構造化情報を抽出します。 3 番目の引数には、自由形式の自然言語による指示 (例: '主な訴え') または '{"field_a": "field a の説明", "field_b": "field b の説明"}' の形式の JSON エンコードされたスキーマを指定できます。 指示モードでは、この関数は抽出した値をプレーンな文字列として返し、何も見つからなかった場合は空文字列を返します。 スキーマモードでは、この関数は要求されたスキーマに対応するキーを持つ JSON オブジェクト文字列を返します。存在しないフィールドは null になります。 最初の引数は、provider、model、endpoint、および API key を指定する named collection です。 構文 
aiExtract(collection, text, instruction_or_schema[, temperature])
別名: AIExtract 引数
  • collection — provider credentials と設定を含む named collection の名前。String
  • text — 情報を抽出するテキスト。String
  • instruction_or_schema — 自由形式の抽出指示、または抽出するフィールドを記述した定数の JSONオブジェクト。const String
  • temperature — ランダム性を制御するサンプリング温度。デフォルト: 0.0。const Float64
戻り値 単一の抽出結果 (指示モード) または JSONオブジェクト文字列 (スキーマモード) 。リクエストが失敗し、ai_function_throw_on_error が無効になっている場合は、カラム型のデフォルト値 (空文字列) を返します。String 例 自由形式の指示
Query
SELECT aiExtract('ai_credentials', 'The package arrived late and was damaged.', 'the main complaint')
Response
late and damaged package
スキーマ抽出
Query
SELECT aiExtract('ai_credentials', review, '{"sentiment": "positive, negative or neutral", "topic": "main topic of the review"}') FROM reviews LIMIT 5
Response

​
aiGenerate

導入バージョン: v26.4.0 LLMプロバイダーを使用して、プロンプトから自由形式のテキストコンテンツを生成します。 この関数は、設定されたAIプロバイダーにプロンプトを送信し、生成されたテキストを返します。 任意のシステムプロンプトを指定して、モデルの挙動 (例: トーン、フォーマット、ロール) を制御できます。 システムプロンプトが指定されていない場合、デフォルトのシステムプロンプトは次のとおりです: You are a helpful assistant. Provide a clear and concise response. 最初の引数は、プロバイダー、モデル、エンドポイント、APIキーを指定する名前付きコレクションです。 構文 
aiGenerate(collection, prompt[, system_prompt[, temperature]])
別名: AIGenerate 引数
  • collection — provider credentials と configuration を含む named collection の名前。String
  • prompt — モデルに送信するユーザーのプロンプトまたは質問。String
  • system_prompt — モデルの動作を導く任意の固定のシステムレベル命令 (例: ペルソナ、出力フォーマット) 。各プロンプトとともに送信されます。String
  • temperature — ランダム性を制御するサンプリング温度。デフォルト: 0.7。Float64
戻り値 生成されたテキスト応答。リクエストが失敗し、ai_function_throw_on_error が無効な場合は、カラム型のデフォルト値 (空文字列) が返されます。String 例 簡単な質問
Query
SELECT aiGenerate('ai_credentials', 'What is 2 + 2? Reply with just the number.')
Response
4
システムプロンプトあり
Query
SELECT aiGenerate('ai_credentials', 'Explain ClickHouse', 'You are a database expert. Be concise.')
Response
カラム値を要約
Query
SELECT article_title, aiGenerate('ai_credentials', concat('Summarize in one sentence: ', article_body)) AS summary FROM articles LIMIT 5
Response

​
aiTranslate

導入バージョン: v26.4.0 指定したテキストを、LLMプロバイダーを使用して指定した対象言語に翻訳します。 文体や方言に関する追加の指示は、第4引数として渡せます (例: 'keep technical terms untranslated') 。 最初の引数は、プロバイダー、モデル、エンドポイント、API key を指定する named collection です。 構文 
aiTranslate(collection, text, target_language[, instructions[, temperature]])
別名: AITranslate 引数
  • collection — provider credentials と configuration を含む名前付きコレクションの名前。String
  • text — 翻訳するテキスト。String
  • target_language — 翻訳先言語の名前または BCP-47 コード (例: 'French'、'es-MX') 。String
  • instructions — 翻訳者への追加指示 (任意の定数) 。String
  • temperature — ランダム性を制御するサンプリング温度。デフォルト: 0.3。Float64
戻り値 翻訳されたテキスト、またはリクエストが失敗し、ai_function_throw_on_error が無効な場合はカラム型のデフォルト値 (空文字列) 。String 例 フランス語に翻訳
Query
SELECT aiTranslate('ai_credentials', 'Hello, world!', 'French')
Response
Bonjour le monde!
スタイル指示に従って日本語に翻訳してください
Query
SELECT aiTranslate('ai_credentials', body, 'Japanese', 'Use polite form (desu/masu)') FROM articles LIMIT 5
Response
最終更新日 2026年6月10日