AI 함수

AI 함수는 ClickHouse에 내장된 함수로, AI를 호출하거나 임베딩을 생성해 데이터를 활용하고, 정보를 추출하고, 데이터를 분류하는 등의 작업에 사용할 수 있습니다…

AI 함수는 실험적 기능입니다. 이를 활성화하려면 allow_experimental_ai_functions을 설정하십시오.AI 함수는 예측하기 어려운 출력을 반환할 수 있습니다. 결과는 프롬프트의 품질과 사용된 모델에 크게 좌우됩니다.

프롬프트 인젝션입력 텍스트는 모델로 전송되며 모델의 출력을 유도할 수 있습니다(프롬프트 인젝션). 외부의 검증되지 않았거나 정제되지 않은 출처의 텍스트에는 모델이 공격자가 제어하는 콘텐츠를 반환하게 하거나, 요청된 형식을 무시하거나, 악성 페이로드를 출력하게 하는 지침이 포함될 수 있습니다. AI 함수 출력은 신뢰할 수 없는 것으로 간주하십시오. SQL 작성, 셸 명령, 추가 쿼리 또는 액세스 제어 결정과 같은 후속 단계에서 사용하기 전에 이를 검증하거나 정제하십시오.

모든 함수는 다음을 제공하는 공통 인프라를 기반으로 합니다:

Quota 적용: 토큰에 대한 쿼리별 제한(ai_function_max_input_tokens_per_query, ai_function_max_output_tokens_per_query) 및 API 호출 제한(ai_function_max_api_calls_per_query).
백오프를 사용하는 재시도: 일시적인 실패는 지수형 백오프(ai_function_retry_initial_delay_ms)를 적용하여 재시도됩니다(ai_function_max_retries).

구성

AI 함수는 프로바이더 자격 증명과 구성을 저장하는 명명된 컬렉션을 참조합니다. 서로 다른 함수 또는 함수 호출마다 서로 다른 명명된 컬렉션을 생성해 사용할 수 있습니다. 예를 들어 텍스트 함수(aiGenerate, aiClassify, aiFilter, aiExtract, aiTranslate, aiRedact)에 사용할 명명된 컬렉션과 임베딩 함수(aiEmbed, aiSimilarity)에 사용할 명명된 컬렉션을 별도로 정의할 수 있습니다. 각 함수는 서로 다른 엔드포인트가 필요하며, 일반적으로 사용하는 모델도 다릅니다. 프로바이더 자격 증명을 포함하는 명명된 컬렉션을 생성하는 예시 구문은 다음과 같습니다. 하나는 채팅 엔드포인트용이고, 다른 하나는 임베딩 엔드포인트용입니다:

CREATE NAMED COLLECTION ai_text_credentials AS
    provider = 'openai',
    endpoint = 'https://api.openai.com/v1/chat/completions',
    model = 'gpt-4o-mini',
    api_key = 'sk-...';

-- The embedding functions (`aiEmbed`, `aiSimilarity`) do not read `model` from the named collection,
-- pass it as a positional argument instead. Defining `model` in an embedding collection is an error,
-- not silently ignored.
CREATE NAMED COLLECTION ai_embedding_credentials AS
    provider = 'openai',
    endpoint = 'https://api.openai.com/v1/embeddings',
    api_key = 'sk-...';

명명된 컬렉션 매개변수

매개변수	유형	기본값	설명
`provider`	String	—	모델 프로바이더입니다. 지원값: `'openai'`, `'anthropic'`. 아래 참고를 확인하십시오.
`endpoint`	String	—	API 엔드포인트 URL입니다.
`model`	String	—	모델 이름입니다(예: `'gpt-4o-mini'`). 텍스트 함수에서 사용됩니다. 임베딩 함수(`aiEmbed`, `aiSimilarity`)는 위치 인수로 `model`이 필요하며, 명명된 컬렉션에 `model`이 지정된 경우 오류가 발생합니다.
`api_key`	String	—	프로바이더 authentication 키입니다. 선택 사항: 생략하면 auth header가 전송되지 않으므로 authentication이 필요하지 않은 OpenAI 호환 server를 대상으로 지정할 수 있습니다.
`max_tokens`	UInt64	`1024`	API 호출당 최대 출력 토큰 수입니다.
`api_version`	String	—	API 버전 문자열입니다. Anthropic에서 사용됩니다(`'2023-06-01'`).

provider = 'openai'로 설정하고 endpoint가 해당 서비스를 가리키도록 지정하면 모든 OpenAI 호환 API(예: vLLM, Ollama, LiteLLM)를 사용할 수 있습니다.

자격 증명 선택

함수는 다음 순서대로 사용할 명명된 컬렉션을 결정합니다.

있는 경우 매개변수 맵의 credentials 키
그렇지 않으면 해당 기본 자격 증명 설정:
- 텍스트 함수(aiGenerate, aiClassify, aiFilter, aiExtract, aiTranslate, aiRedact)의 경우 ai_function_text_default_credentials
- 임베딩 함수(aiEmbed, aiSimilarity)의 경우 ai_function_embedding_default_credentials

둘 다 설정되지 않으면 호출은 실패합니다. chat-completions 엔드포인트는 embeddings용 엔드포인트와 다르므로, 텍스트 함수와 임베딩 함수는 서로 다른 기본 설정을 사용합니다.

SET ai_function_text_default_credentials = 'ai_text_credentials';

-- Uses ai_text_credentials from the setting:
SELECT aiGenerate('What is 2 + 2? Reply with just the number.');

-- Overrides the default for this call:
SELECT aiGenerate('Bonjour', map('credentials', 'other_credentials'));

UInt8을 반환하고 WHERE에서 직접 사용할 수 있는 aiFilter를 사용하여 자연어 조건으로 행을 필터링합니다:

SELECT * FROM reviews
WHERE aiFilter(body, 'the customer is angry about shipping');

매개변수 맵

각 함수는 선택적으로 끝에 Map(String, String) 형식의 매개변수 맵을 받을 수 있습니다. 모든 값은 문자열이므로 숫자도 '0.2'처럼 따옴표로 감싸야 합니다. 알 수 없는 키는 허용되지 않습니다. 키가 있으면 해당 명명된 컬렉션 값을 재정의하고, 키가 없으면 명명된 컬렉션(model/max_tokens의 경우) 또는 내장 기본값이 사용됩니다. 예외는 임베딩 함수(aiEmbed, aiSimilarity)로, model을 필수 위치 인수로 받으며(예: aiEmbed(text, model[, params]), aiSimilarity(text1, text2, model[, params])), 이를 매개변수 맵이나 명명된 컬렉션에 대신 설정하면 오류가 발생합니다. 이는 재현 가능한 임베딩을 보장하기 위한 것입니다. 다음 매개변수는 모든 AI 함수에 공통입니다:

Key	Description
`credentials`	사용할 명명된 컬렉션입니다(위 참조).
`model`	컬렉션의 `model`을 재정의합니다(텍스트 함수에만 해당하며, 임베딩 함수(`aiEmbed`, `aiSimilarity`)는 `model`을 맵 키가 아니라 필수 위치 인수로 받습니다).

개별 함수는 함수별 추가 매개변수(max_tokens, temperature, system_prompt, instructions, dimensions 등)를 지원합니다. 허용되는 매개변수와 해당 기본값은 아래 각 함수의 참고 문서를 참조하십시오.

SELECT aiGenerate(body, map('temperature', '0.2', 'system_prompt', 'You are terse.')) FROM articles;

쿼리 수준 설정

모든 AI 관련 설정은 설정 문서에서 ai_function_ 접두사 아래에 나열되어 있습니다.

`엔드포인트` 호스트 제한

AI 명명된 컬렉션의 엔드포인트 URL은 서버가 자체 아이덴티티로 연결하는 아웃바운드 대상입니다. 이때 요청 헤더에는 지정된 경우 명명된 컬렉션의 api_key가 포함될 수 있습니다. 기본적으로 ClickHouse는 모든 호스트를 허용합니다. 함수를 특정 프로바이더 집합으로 제한하려면 서버 config에서 remote_url_allow_hosts를 구성하십시오. 예:

<remote_url_allow_hosts>
    <host>api.openai.com</host>
    <host>api.anthropic.com</host>
</remote_url_allow_hosts>

이 설정은 서버 전체에 적용되며 HTTP를 사용하는 모든 기능에 영향을 미친다는 점에 유의하십시오.

전송 보안(HTTP vs HTTPS)

전송 방식은 전적으로 endpoint URL의 스킴에 따라 결정됩니다. 요청 payload에는 애플리케이션 수준의 암호화가 없으므로, 전송 중 데이터 보호는 전적으로 스킴에 달려 있습니다.

https:// — 연결에 TLS를 사용합니다. 요청 본문(입력 텍스트, 프롬프트)과 요청 headers의 api_key는 전송 중 암호화되며, 프로바이더의 certificate도 검증됩니다. 원격 프로바이더를 사용할 때는 항상 이 방식을 사용하십시오.
http:// — 연결이 암호화되지 않습니다. 요청 본문과 api_key가 평문으로 전송됩니다. 신뢰할 수 있는 프로바이더가 프라이빗 네트워크에 있는 경우(예: 로컬 vLLM 또는 Ollama instance)에만 사용하십시오.

기본적으로 AI 함수는 원격 host로 데이터를 평문으로 전송하는 endpoint를 거부합니다. host가 루프백이 아닌 HTTPS 이외의 모든 엔드포인트는 예외를 발생시킵니다. 루프백 host(localhost, 127.0.0.0/8, ::1)는 예외이므로 로컬 http://localhost 모델 server는 별도 설정 없이 작동합니다. 원격 host에서 평문 http:// 엔드포인트를 허용하려면 ai_function_allow_insecure_endpoint를 1로 설정하십시오. 이 검사는 remote_url_allow_hosts와 독립적입니다. 이 설정은 host allowlist이며 URL 스킴은 검사하지 않으므로, 허용된 host를 가리키는 http:// 엔드포인트도 이 검사를 통과합니다. 어느 경우든 프로바이더는 TLS 종료 이후 입력 데이터를 평문으로 받습니다. TLS는 server와 프로바이더 사이의 네트워크 경로에서만 데이터를 보호합니다.

지원되는 프로바이더

프로바이더	`provider` 값	채팅 함수	참고
OpenAI	`'openai'`	예	기본 프로바이더입니다.
Anthropic	`'anthropic'`	예	`/v1/messages` endpoint를 사용합니다.

관측성

AI 함수 활동은 ClickHouse ProfileEvents를 통해 추적됩니다.

ProfileEvent	Description
`AIAPICalls`	AI 프로바이더로 전송된 HTTP 요청 수입니다.
`AIInputTokens`	사용된 총 입력 토큰 수입니다.
`AIOutputTokens`	사용된 총 출력 토큰 수입니다.
`AIRowsProcessed`	결과를 받은 행 수입니다.
`AIRowsSkipped`	건너뛴 행 수입니다(QUOTA를 초과했거나 `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 프로바이더를 사용해 주어진 텍스트를 제공된 범주 중 하나로 분류합니다. 자격 증명(프로바이더, 모델, endpoint와 선택적으로 API Key를 지정하는 명명된 컬렉션)은 선택적 매개변수 맵의 credentials 키에서 가져오며, 맵에 이 키가 없으면 ai_function_text_default_credentials 설정에서 가져옵니다. 구문

aiClassify(text, categories[, params])

별칭: AIClassify 인수

text — 분류할 텍스트입니다. String
categories — 후보 카테고리 레이블의 상수 목록입니다. Array(String)
params — 선택적 상수 Map(String, String) 매개변수입니다. 함수별 키는 temperature(무작위성을 제어하는 샘플링 온도, 기본값 0.0), max_tokens(호출당 최대 출력 토큰 수, 기본값 1024)입니다. 공통 매개변수 credentials 및 model도 적용됩니다(AI 함수 참고). Map(String, String)

반환 값 제공된 카테고리 레이블 중 하나를 반환합니다. 요청이 실패하고 ai_function_throw_on_error가 비활성화된 경우에는 컬럼 타입의 기본값(빈 문자열)을 반환합니다. String 예시 감정 분류

Query

SELECT aiClassify('I love this product!', ['positive', 'negative', 'neutral'])

Response

positive

명시적 자격 증명을 사용해 컬럼 분류

Query

SELECT body, aiClassify(body, ['bug', 'question', 'feature'], map('credentials', 'ai_text_credentials')) AS kind FROM issues LIMIT 5

aiEmbed

도입 버전: v26.6.0 구성된 AI 프로바이더를 사용하여 지정된 텍스트의 임베딩 벡터를 생성합니다. 이 함수는 텍스트를 구성된 임베딩 엔드포인트로 전송하고, 결과 벡터를 Array(Float32)로 반환합니다. 단일 block의 행 내에서는 호출별 overhead를 줄이기 위해 입력이 HTTP 요청당 최대 ai_function_embedding_max_batch_size 개 항목의 batch로 그룹화됩니다. 자격 증명(프로바이더, 엔드포인트, 그리고 선택적으로 API Key를 지정하는 명명된 컬렉션)은 매개변수 맵의 credentials 키에서 가져오며, 맵에서 이를 생략한 경우 ai_function_embedding_default_credentials 설정에서 가져옵니다. 임베딩 엔드포인트는 chat 엔드포인트와 다르므로 aiEmbed는 텍스트 함수와 별도의 기본 자격 증명 설정을 사용한다는 점에 유의하십시오. model은 필수 위치 인수(상수 String)입니다. 텍스트 함수와 달리 aiEmbed는 명명된 컬렉션이나 매개변수 맵에서 model을 읽지 않습니다. model을 정의하는 명명된 컬렉션은 거부됩니다. 선택적 dimensions 매개변수는 모델이 이를 지원하는 경우(예: OpenAI’s text-embedding-3-*) 지정한 크기의 벡터를 요청하며, 그렇지 않으면 모델의 네이티브 크기가 반환됩니다. 구문

aiEmbed(text, model[, params])

별칭: AIEmbed 인수

text — 임베딩할 텍스트입니다. String
model — 임베딩 모델 이름입니다. const String
params — 선택적 상수 Map(String, String) 매개변수입니다. 함수별 키는 dimensions입니다(출력 벡터의 대상 차원 수이며, 0이거나 생략하면 모델의 네이티브 크기를 의미합니다). 공통 매개변수 credentials도 적용됩니다(AI 함수 참조). Map(String, String)

반환 값 임베딩 벡터 또는 빈 배열을 반환합니다. 입력이 NULL이거나 비어 있는 경우, 요청이 실패했지만 ai_function_throw_on_error가 비활성화된 경우, 또는 QUOTA를 초과했지만 ai_function_throw_on_quota_exceeded가 비활성화된 경우에는 빈 배열이 반환됩니다. Array(Float32) 예시 단일 문자열 임베딩(ai_function_embedding_default_credentials 설정이 지정된 경우 credentials는 생략할 수 있습니다)

Query

SELECT aiEmbed('Hello world', 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials'))

차원을 명시적으로 지정하는 경우

Query

SELECT aiEmbed('Hello world', 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials', 'dimensions', '256'))

텍스트 컬럼 임베드하기

Query

SELECT aiEmbed(title, 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials', 'dimensions', '256')) FROM articles LIMIT 10

aiExtract

도입 버전: v26.4.0 LLM 프로바이더를 사용해 비구조화 텍스트에서 구조화된 정보를 추출합니다. 세 번째 인수는 자유 형식의 자연어 지시문(예: 'the main complaint')이거나 '{"field_a": "description of field a", "field_b": "description of field b"}' 형태의 JSON 인코딩 스키마일 수 있습니다. 지시문 모드에서 이 함수는 추출된 값을 일반 문자열로 반환하고, 아무것도 찾지 못하면 빈 문자열을 반환합니다. 스키마 모드에서 이 함수는 키가 요청한 스키마와 일치하는 JSON 객체 문자열을 반환하며, 누락된 필드는 null로 반환됩니다. 자격 증명(프로바이더, 모델, endpoint 및 선택적으로 API Key를 지정하는 명명된 컬렉션)은 선택적 매개변수 맵의 credentials key에서 가져오며, map에 이 항목이 없으면 ai_function_text_default_credentials setting에서 가져옵니다. 구문

aiExtract(text, instruction_or_schema[, params])

별칭: AIExtract 인수

text — 정보를 추출할 텍스트입니다. String
instruction_or_schema — 자유 형식의 추출 지침 또는 추출할 필드를 설명하는 상수 JSON 객체입니다. const String
params — 선택 사항인 상수 Map(String, String) 파라미터입니다. 함수별 키는 temperature(무작위성을 제어하는 샘플링 온도, 기본값 0.0)와 max_tokens(호출당 최대 출력 토큰 수, 기본값 1024)입니다. 공통 매개변수 credentials 및 model도 적용됩니다(AI 함수 참조). Map(String, String)

반환 값 단일 추출 값(지침 모드) 또는 JSON 객체 문자열(스키마 모드)입니다. 요청이 실패하고 ai_function_throw_on_error가 비활성화되어 있으면 컬럼 타입의 기본값(빈 문자열)을 반환합니다. String 예시 자유 형식 추출 지침

Query

SELECT aiExtract('The package arrived late and was damaged.', 'the main complaint')

Response

late and damaged package

스키마 추출

Query

SELECT aiExtract(review, '{"sentiment": "positive, negative or neutral", "topic": "main topic of the review"}') FROM reviews LIMIT 5

aiFilter

도입 버전: v26.8.0 LLM 프로바이더를 사용하여 지정된 텍스트에 자연어 조건을 적용하고, WHERE, PREWHERE, JOIN ... ON에 사용할 수 있는 Boolean(UInt8) 값을 반환합니다. 이 FUNCTION은 모델이 소문자 true 또는 false로만 응답하도록 요청합니다. 실패한 request(ai_function_throw_on_error가 비활성화된 경우)와 인식할 수 없는 응답은 0으로 매핑되므로 해당 행은 필터링됩니다. Warning: 면밀히 검토하지 않은 aiFilter 결과를 신뢰하지 마십시오. LLM 기반 프레디케이트는 부정확하거나 일관되지 않을 수 있으므로 false positive와 false negative를 허용할 수 있는 경우에만 사용하십시오. 자격 증명(LLM 프로바이더, 모델, 엔드포인트 및 선택적으로 API Key를 지정하는 명명된 컬렉션)은 선택적 매개변수 맵의 credentials key에서 가져오며, 맵에 해당 항목이 없으면 ai_function_text_default_credentials SETTING에서 가져옵니다. Note: JOIN ... ON에서 aiFilter를 사용하면 candidate 쌍마다 LLM을 한 번씩 평가하므로 비용이 많이 들 수 있습니다. 구문

aiFilter(text, condition[, params])

별칭: AIFilter 인수

text — 평가할 텍스트입니다. String
condition — 텍스트가 충족해야 하는 상수 자연어 조건입니다. String
params — 선택적으로 지정하는 상수 Map(String, String) 매개변수입니다. 함수별 키는 다음과 같습니다. temperature(무작위성을 제어하는 샘플링 온도, 기본값 0.0), max_tokens(호출당 최대 출력 토큰 수, 기본값 1024). 공통 매개변수인 credentials 및 model도 적용됩니다(AI 함수 참조). Map(String, String)

반환 값 텍스트가 조건을 충족하면 1, 그렇지 않으면 0을 반환합니다. 요청이 실패하고 ai_function_throw_on_error가 비활성화된 경우 기본값(0)을 반환합니다. UInt8 예시 부정적인 리뷰 필터링

Query

SELECT * FROM reviews WHERE aiFilter(body, 'the customer is angry about shipping')

명시적으로 제공한 자격 증명으로 컬럼 필터링

Query

SELECT body, aiFilter(body, 'describes a bug', map('credentials', 'ai_text_credentials')) AS is_bug FROM issues LIMIT 5

aiGenerate

도입된 버전: v26.4.0 LLM 프로바이더를 사용해 프롬프트로부터 자유 형식의 텍스트 콘텐츠를 생성합니다. 이 함수는 프롬프트를 설정된 AI 프로바이더로 전송하고, 생성된 텍스트를 반환합니다. 자격 증명(프로바이더, 모델, endpoint, 그리고 선택적으로 API Key를 지정하는 명명된 컬렉션)은 선택적 매개변수 맵의 credentials 키에서 가져오며, 맵에 해당 항목이 없으면 ai_function_text_default_credentials 설정에서 가져옵니다. 선택적 매개변수 맵에서는 system_prompt(어조, 포맷, 역할 등 모델의 동작을 안내하는 지시문), temperature, max_tokens, model도 설정할 수 있습니다. system_prompt가 설정되지 않으면 기본값은 다음과 같습니다: You are a helpful assistant. Provide a clear and concise response. 구문

aiGenerate(prompt[, params])

별칭: AIGenerate 인수

prompt — 모델에 보낼 사용자 프롬프트 또는 질문입니다. String
params — 선택적 상수 Map(String, String) 매개변수 맵입니다. 함수별 키는 다음과 같습니다: temperature (무작위성을 제어하는 샘플링 온도, 기본값 0.7), max_tokens (호출당 최대 출력 토큰 수, 기본값 1024), system_prompt (모델 동작을 안내하는 상수 시스템 수준 지침, 기본값은 일반적인 어시스턴트 프롬프트). 공통 매개변수인 credentials와 model도 적용됩니다(AI 함수 참조). Map(String, String)

반환 값 생성된 텍스트 응답 또는 요청이 실패하고 ai_function_throw_on_error가 비활성화된 경우 컬럼 타입의 기본값(빈 문자열)입니다. String 예시 간단한 질문

Query

SELECT aiGenerate('What is 2 + 2? Reply with just the number.')

Response

명시적 자격 증명과 시스템 프롬프트 사용

Query

SELECT aiGenerate('Explain ClickHouse', map('credentials', 'ai_text_credentials', 'system_prompt', 'You are a database expert. Be concise.'))

컬럼 값 요약

Query

SELECT article_title, aiGenerate(concat('Summarize in one sentence: ', article_body)) AS summary FROM articles LIMIT 5

aiRedact

도입 버전: v26.8.0 LLM 프로바이더를 사용하여 지정된 텍스트에서 개인 식별 정보(PII)를 감지하고 마스킹합니다.

aiRedact는 LLM을 사용해 최선의 노력으로 PII를 감지하고 마스킹하므로, 출력 결과를 신뢰할 수 없습니다. PII의 감지 및 제거 여부는 선택한 모델, 프롬프트, 입력에 따라 달라집니다. 모델은 식별자를 놓치거나 일부만 마스킹하거나 주변 텍스트를 변경할 수 있습니다. 형식이 잘 갖춰진 영어 텍스트에서 가장 잘 작동하며, 다른 언어 또는 철자, 문장 부호, 문법 오류가 많은 텍스트에서는 결과가 더 나쁠 수 있습니다. aiRedact는 출력에 PII가 없음을 보장하지 않으며, 그 자체로 안전하거나 충분한 익명화 수단으로 간주해서는 안 됩니다. 신뢰할 수 없는 당사자에게 데이터를 노출하기 전에 항상 출력을 검토하여 조직의 데이터 개인정보 보호 및 컴플라이언스 정책을 충족하는지 확인하십시오.

감지된 각 PII 스팬은 마스킹 토큰(기본값은 [REDACTED]이며, replacement 매개변수로 구성 가능)으로 대체됩니다. categories 배열은 마스킹할 PII 유형을 제한하며, 빈 배열을 지정하면 일반적인 카테고리(이름, 이메일, 전화번호, 주소, 신용카드, IP 주소)의 기본 세트가 사용됩니다. aiRedact는 모델에 감지된 PII 스팬만 변경하도록 지시하지만, 주변 텍스트 보존은 최선의 노력으로만 이루어지므로 모델이 여전히 이를 변경할 수 있습니다(위 경고 참고). 탭, 줄바꿈, 캐리지 리턴 이외의 제어 문자는 요청 전에 공백으로 정규화되므로, 이러한 문자가 포함된 입력의 경우 출력은 입력과 바이트 단위로 동일하지 않습니다. aiRedact는 PII가 대체된 전체 입력 텍스트를 반환하므로 출력 길이는 입력과 거의 같습니다. max_tokens(기본값 1024)는 입력의 토큰 길이보다 크게 설정하십시오. 제한값이 너무 낮아 응답이 잘리면 불완전해집니다. 구문

aiRedact(text, categories[, params])

별칭: AIRedact 인수

text — 마스킹할 텍스트입니다. String
categories — 마스킹할 PII 카테고리의 상수 목록입니다(예: ['name', 'ssn', 'credit_card']). 빈 배열을 지정하면 일반적인 카테고리(이름, 이메일, 전화번호, 주소, 신용카드, IP 주소)의 기본 집합이 사용됩니다. Array(String)
params — 선택적 상수 Map(String, String) 매개변수입니다. 함수별 키는 다음과 같습니다. temperature(무작위성을 제어하는 샘플링 온도, 기본값 0.0), max_tokens(호출당 최대 출력 토큰 수, 기본값 1024 — aiRedact는 전체 텍스트를 반환하므로 입력 토큰 수보다 크게 설정해야 합니다. 그렇지 않으면 응답이 잘리거나 불완전할 수 있습니다), replacement(감지된 각 PII 스팬을 대체할 토큰, 기본값 [REDACTED]). 공통 매개변수인 credentials 및 model도 적용됩니다(AI 함수 참조). Map(String, String)

반환 값 감지된 PII를 마스킹 토큰으로 대체한 텍스트입니다. 요청에 실패하고 ai_function_throw_on_error가 비활성화된 경우에는 컬럼 타입의 기본값(빈 문자열)을 반환합니다. String 예시 특정 카테고리 마스킹

Query

SELECT aiRedact('Purchase was done by customer John Doe with email test@test.org', ['email', 'credit_card', 'name'])

Response

Purchase was done by customer [REDACTED] with email [REDACTED]

사용자 지정 토큰으로 기본 PII 카테고리를 마스킹합니다

Query

SELECT aiRedact(body, [], map('replacement', '***')) FROM tickets LIMIT 5

aiSimilarity

도입 버전: v26.8.0 구성된 임베딩 제공자를 사용하여 두 텍스트의 의미적 유사도를 계산합니다. 두 텍스트의 벡터 임베딩을 계산하고 코사인 유사도를 반환합니다. 점수 -1은 서로 반대 방향을 가리키는 임베딩 벡터에 해당하며, 의미적으로 점수가 -1에 가까운 텍스트는 의미가 반대임을 뜻합니다. 점수 0은 벡터가 직교함을 의미하며, 의미적으로 서로 관련이 없습니다. 마지막으로 점수 1은 임베딩 벡터가 같은 방향을 가리킴을 의미하며, 점수가 1에 가까운 텍스트는 의미가 유사합니다. 이는 동일한 임베딩에 대한 cosineDistance의 보수입니다 (aiSimilarity = 1 - cosineDistance(embedding1, embedding2)). 배칭, 자격 증명 및 dimensions 매개변수는 ai_function_embedding_default_credentials 기본 자격 증명 설정을 포함하여 aiEmbed와 동일합니다. aiEmbed와 마찬가지로 model은 명명된 컬렉션이나 매개변수 맵에서 읽어 오지 않는 필수 위치 인수(상수 String)입니다. 구문

aiSimilarity(text1, text2, model[, params])

별칭: AISimilarity 인수

text1 — 첫 번째 텍스트입니다. String
text2 — 두 번째 텍스트입니다. String
model — 임베딩 모델 이름입니다. const String
params — 선택적 상수 Map(String, String) 매개변수입니다. 함수별 키는 dimensions입니다(임베딩의 대상 차원 수이며, 0 또는 생략 시 모델의 네이티브 크기를 사용합니다). 공통 매개변수 credentials도 적용됩니다(AI 함수 참조). Map(String, String)

반환 값 [-1, 1] 범위의 코사인 유사도입니다. 두 텍스트 중 하나가 NULL이거나 비어 있는 경우, 임베딩 요청이 실패했고 ai_function_throw_on_error가 비활성화된 경우 또는 QUOTA를 초과했고 ai_function_throw_on_quota_exceeded가 비활성화된 경우에는 NULL을 반환합니다. Nullable(Float32) 예시 두 문자열 비교(ai_function_embedding_default_credentials 설정이 지정되어 있으면 credentials를 생략할 수 있음)

Query

SELECT aiSimilarity('cat', 'kitten', 'text-embedding-3-small', map('credentials', 'ai_embedding_credentials'))

쿼리와의 유사도에 따라 리뷰 순위 지정

Query

SELECT review FROM product_reviews ORDER BY aiSimilarity(review, 'It works well under rain', 'text-embedding-3-small') DESC LIMIT 100

self-join을 통한 의미 기반 중복 제거

Query

SELECT a.id, b.id FROM docs a, docs b WHERE a.id < b.id AND aiSimilarity(a.title, b.title, 'text-embedding-3-small') > 0.9

aiTranslate

도입 버전: v26.4.0 주어진 텍스트를 LLM 프로바이더를 사용해 지정된 대상 언어로 번역합니다. 추가 스타일 또는 방언 관련 지침은 매개변수 맵의 instructions 키를 통해 전달할 수 있습니다(예: '기술 용어는 번역하지 않음'). 자격 증명(프로바이더, model, endpoint, 그리고 선택적으로 API Key를 지정하는 명명된 컬렉션)은 선택적 매개변수 맵의 credentials 키에서 가져오며, 맵에 해당 항목이 없으면 ai_function_text_default_credentials 설정에서 가져옵니다. 구문

aiTranslate(text, target_language[, params])

별칭: AITranslate 인수

text — 번역할 텍스트입니다. String
target_language — 대상 언어 이름 또는 BCP-47 코드입니다(예: 'French', 'es-MX'). String
params — 선택적 상수 Map(String, String) 매개변수입니다. 함수별 키는 다음과 같습니다. temperature(무작위성을 제어하는 샘플링 온도, 기본값 0.3), max_tokens(호출당 최대 출력 토큰 수, 기본값 1024), instructions(번역기에 대한 추가 스타일 또는 방언 지침). 공통 매개변수인 credentials와 model도 적용됩니다(AI Functions 참조). Map(String, String)

반환 값 번역된 텍스트를 반환합니다. 요청이 실패하고 ai_function_throw_on_error가 비활성화된 경우에는 컬럼 타입의 기본값(빈 문자열)을 반환합니다. String 예시 프랑스어로 번역

Query

SELECT aiTranslate('Hello, world!', 'French')

Response

Bonjour le monde!

스타일 지침에 따라 일본어로 번역

Query

SELECT aiTranslate(body, 'Japanese', map('instructions', 'Use polite form (desu/masu)')) FROM articles LIMIT 5

SQL 참고

데이터 타입

엔진

함수

포맷

인터페이스

설정

시스템 테이블

데이터 레이크

구성

명명된 컬렉션 매개변수

자격 증명 선택

매개변수 맵

쿼리 수준 설정

`엔드포인트` 호스트 제한

전송 보안(HTTP vs HTTPS)

지원되는 프로바이더

관측성

aiClassify

aiEmbed

aiExtract

aiFilter

aiGenerate

aiRedact

aiSimilarity

aiTranslate

​구성

​명명된 컬렉션 매개변수

​자격 증명 선택

​매개변수 맵

​쿼리 수준 설정

​엔드포인트 호스트 제한

​전송 보안(HTTP vs HTTPS)

​지원되는 프로바이더

​관측성

​aiClassify

​aiEmbed

​aiExtract

​aiFilter

​aiGenerate

​aiRedact

​aiSimilarity

​aiTranslate

구성

명명된 컬렉션 매개변수

자격 증명 선택

매개변수 맵

쿼리 수준 설정

`엔드포인트` 호스트 제한

전송 보안(HTTP vs HTTPS)

지원되는 프로바이더

관측성

aiClassify

aiEmbed

aiExtract

aiFilter

aiGenerate

aiRedact

aiSimilarity

aiTranslate