EXPERIMENT

EXPERIMENT (CREATE / EXECUTE / SHOW / DROP)

실험(experiment)은 AI 워크로드(평가 또는 최적화)를 패키징하고 그 결과를 일련의 실행(runs)으로 기록하는 스키마 수준의 Snowflake 객체예요. 명세로 실험을 만들고 비동기(서버리스 컴퓨팅)로 실행한 뒤, SHOW 명령으로 실행, 메트릭, 파라미터를 읽어요.

출처: 문서

본문

실험은 AI 평가와 최적화의 전달 메커니즘이에요. 이 페이지는 객체 자체의 명령 참조예요:

  • CREATE EXPERIMENT — 실험과 그 spec을 정의.
  • EXECUTE EXPERIMENT — 실행(비동기).
  • SHOW RUNS / SHOW RUN METRICS / SHOW RUN PARAMETERS — 결과를 읽음.
  • DESCRIBE / SHOW EXPERIMENTS / ALTER / DROP — 실험 관리.

CREATE EXPERIMENT

실험 객체를 만들어요. 평가와 최적화의 경우 FROM SPECIFICATION으로 명세를 연결해요.

구문

CREATE [ OR REPLACE ] EXPERIMENT [ IF NOT EXISTS ] <name>
  [ TYPE = '<experiment_type>' ]
  [ FROM SPECIFICATION $$ <yaml> $$ ]

인자 (Arguments)

필수:

  • name — 실험 식별자. 정규화될 수 있어요(db.schema.name).

선택:

  • TYPE = 'experiment_type' — 실험 유형. 허용 값(대소문자 무시):
Type 목적 Specification
AI_FUNCTION_EVALUATION 레이블된 데이터에 대해 AI 호출을 측정. Evaluate
AI_FUNCTION_OPTIMIZATION AI 함수를 자동으로 개선. Optimize

TYPE을 생략하면 일반(타입 없음) 실험이 만들어지며, 실행을 보유하지만 EXECUTE EXPERIMENT로는 실행할 수 없어요.

  • FROM SPECIFICATION $$ ... $$ — $$...$$(또는 일반 문자열 리터럴)로 묶은 실험의 YAML 명세. 명세는 생성 시점에 해석된 TYPE의 스키마에 대해 검증되며, 알 수 없거나 잘못 입력된 키는 거부돼요.
  • OR REPLACE — 같은 이름의 기존 실험을 교체.
  • IF NOT EXISTS — 실험이 이미 존재하면 오류 없음.

실행 가능하려면 실험에 eval/opt TYPE과 비어 있지 않은 명세가 모두 있어야 해요.

EXECUTE EXPERIMENT

이전에 만든 실험을 실행해요. 작업은 서버리스 컴퓨팅에서 비동기로 예약되고 결과는 실행으로 기록돼요.

구문

EXECUTE EXPERIMENT <name>

동작 (Behavior)

  • 비동기. EXECUTE EXPERIMENT는 작업을 서버리스 태스크로 예약하고 상태 메시지를 즉시 반환하며, 차단하거나 실행 데이터를 반환하지 않아요. 실행이 종료 상태에 도달할 때까지 SHOW RUNS를 폴링해요. 스핀업은 일반적으로 몇 분 걸려요.
  • 옵션 없음. 문장은 실험 이름만 사용해요. 인자, USING, WITH 절, 명시적 ASYNC 키워드가 없어요(비동기는 암시적).
  • 실험당 한 번 실행. 완료된 실험을 다시 실행하면 거부돼요(EXPERIMENT_ALREADY_EXECUTED). 실행이 진행 중일 때 다시 실행하는 것은 no-op 성공이에요. 다시 실행하려면 새 실험을 만들거나(CREATE OR REPLACE) 해요.
  • 시간 제한. 실행은 20시간의 실행 시간으로 제한되며, 초과하는 실행은 종료돼요. 대부분의 작업은 이 제한 안에 잘 끝나요.
  • 전제 조건(충족되지 않으면 각각 사용자에게 보이는 오류 발생): 실험 존재, eval/opt TYPE 보유, 비어 있지 않은 spec 보유, 호출자가 필요한 Cortex 역할 보유.

실행 중인 실험 취소

ALTER EXPERIMENT <name> ABORT;

결과 읽기 (Reading results)

실행된 실험은 작업을 실행으로 기록해요. 실행 이름은 유형에 따라 달라져요:

  • 평가(Evaluation) → EVAL_1, EVAL_2, … (각 num_eval_runs당 하나).
  • 최적화(Optimization) → SEED(기준선) + ITER_1, ITER_2, …(후보).

SHOW RUNS

SHOW RUNS [ LIKE '<pattern>' ] IN EXPERIMENT <name>
  [ LIMIT <n> [ FROM '<name>' ] ]

실행을 나열해요. 수명 주기 상태는 별도의 최상위 열이 아니라 메타데이터 JSON 열 안에 있어요({"status":"FINISHED"|"FAILED"|"RUNNING", ...}). RUNNING은 실험이 여전히 작업 중임을 뜻해요. 최적화 실행은 전체 검색이 끝날 때까지 RUNNING 상태로 유지되다가 배치로 커밋돼요.

SHOW RUN METRICS / SHOW RUN PARAMETERS

SHOW RUN METRICS    [ LIKE '<pattern>' ] IN EXPERIMENT <name>
  [ RUN <run_name> ] [ LIMIT <n> ]

SHOW RUN PARAMETERS [ LIKE '<pattern>' ] IN EXPERIMENT <name>
  [ RUN <run_name> ] [ LIMIT <n> ]
  • IN EXPERIMENT <name> — 필수.
  • RUN <run_name> — 선택. 하나의 실행으로 범위를 한정. 실행 이름은 따옴표 없이(RUN SEED) 또는 따옴표로(RUN 'SEED') 쓸 수 있어요. RUN을 생략하면 모든 실행에 걸쳐 나열됨.

메트릭은 숫자예요. 평가 실행은 score, 최적화 실행은 val_score, test_score, cost_compared_to_seed, is_frontier. 파라미터는 문자열 값이에요(예: model, function_name, function_impl, run_type, parent_candidate, rows_evaluated).

실험 관리 (Managing experiments)

DESCRIBE EXPERIMENT

{ DESCRIBE | DESC } EXPERIMENT <name>

실험의 메타데이터를 반환해요: created_on, name, database_name, schema_name, owner, 그리고(활성화되면) type과 spec.

SHOW EXPERIMENTS

SHOW EXPERIMENTS [ LIKE '<pattern>' ]
  [ IN { ACCOUNT | DATABASE [ <name> ] | SCHEMA [ <name> ] } ]

DROP EXPERIMENT

DROP EXPERIMENT [ IF EXISTS ] <name>

실험을 삭제하면 그 실행도 제거돼요. 실행을 포기하려는 것이 아니라면 EXECUTE EXPERIMENT가 진행 중일 때 실험을 삭제하지 마세요. 먼저 ALTER EXPERIMENT <name> ABORT로 취소해요.

사용 메모 (Usage notes)

  • 비동기 수명 주기. EXECUTE EXPERIMENT가 작업 완료 전에 반환하므로 항상 SHOW RUNS를 폴링하고 metadata.status를 확인해요. 새로 실행된 실험은 실행이 RUNNING → FINISHED(또는 FAILED)로 전환되는 것을 보여줘요.
  • 실행 중 객체 유지. 실행 중인 실험이 참조하는 함수, 데이터셋, 실험은 실행 기간 동안 존재해야 해요. 실행 중에 삭제하면 실행이 실패해요.
  • 반복은 CREATE OR REPLACE. 실험은 한 번만 실행되므로 일반적인 루프는: 조정된 spec으로 CREATE OR REPLACE EXPERIMENT ..., 그런 다음 EXECUTE EXPERIMENT 다시 실행.
  • 데이터셋은 버전화된 SNOWFLAKE.ML.DATASET 객체여야 해요. eval과 opt spec 모두에서 일반 테이블/뷰는 허용되지 않아요.
  • 데이터셋 크기. 약 50–200행의 데이터셋이 권장되며, 최대는 1,000행이에요(eval 및 opt spec 모두 적용).

과금 (Billing)

EXECUTE EXPERIMENT는 서버리스 컴퓨팅에서 실행되며, SERVERLESS_EXPERIMENTS 서비스 유형으로 표준 서버리스 컴퓨팅 크레딧 요율로 계량돼요. 실험이 수행하는 AI 추론(AI_COMPLETE 및 관련 호출)은 Cortex AI 사용량(토큰)으로 별도 계량돼요. 사용량은 다음에서 볼 수 있어요:

  • SNOWFLAKE.ACCOUNT_USAGE.SERVERLESS_EXPERIMENT_HISTORY — 실험당 크레딧과 시간, 실험 이름, 데이터베이스, 스키마 포함.
  • SNOWFLAKE.ACCOUNT_USAGE.METERING_HISTORY / METERING_DAILY_HISTORY — SERVICE_TYPE = 'SERVERLESS_EXPERIMENTS'로 필터.
  • 조직 전체 보고용 해당 ORGANIZATION_USAGE 뷰.

접근 제어 요구사항 (Access control requirements)

Privilege / role Object 필요 용도
CREATE EXPERIMENT Schema CREATE EXPERIMENT.
MODIFY (또는 OWNERSHIP) Experiment EXECUTE EXPERIMENT, ALTER EXPERIMENT ... ABORT(실행은 실행을 생성하며 MODIFY 필요).
OWNERSHIP Experiment DROP EXPERIMENT.
USAGE (또는 어떤 grant) Experiment DESCRIBE, SHOW RUNS / SHOW RUN METRICS / SHOW RUN PARAMETERS.
Database role SNOWFLAKE.CORTEX_USER (또는 SNOWFLAKE.AI_FUNCTIONS_USER) — EXECUTE EXPERIMENT.
USAGE 참조된 함수/데이터셋 db + schema 워크로드 실행.

예시 (Examples)

최적화 실험 만들고, 실행하고, 읽기

CREATE OR REPLACE EXPERIMENT my_db.my_schema.redact_opt_exp
  TYPE = 'AI_FUNCTION_OPTIMIZATION'
  FROM SPECIFICATION $$
function:
  function_name: "my_db.my_schema.redact(VARCHAR)"
metrics:
  - name: redaction_match
dataset:
  name: my_db.my_schema.redaction_ds
  version: v1
  column_mapping:
    argument_mapping:
      text: text_col
    ground_truth: expected_output
optimization:
  models:
    - claude-haiku-4-5
  reflection_model: claude-sonnet-4-5
  budget: ultra-light
$$;

EXECUTE EXPERIMENT my_db.my_schema.redact_opt_exp;

-- Poll until terminal, then read metrics.
SHOW RUNS IN EXPERIMENT my_db.my_schema.redact_opt_exp;
SHOW RUN METRICS IN EXPERIMENT my_db.my_schema.redact_opt_exp RUN SEED;
SHOW RUN METRICS IN EXPERIMENT my_db.my_schema.redact_opt_exp RUN ITER_1;

나열 및 정리

SHOW EXPERIMENTS IN SCHEMA my_db.my_schema;
DESCRIBE EXPERIMENT my_db.my_schema.redact_opt_exp;
DROP EXPERIMENT IF EXISTS my_db.my_schema.redact_opt_exp;

제한 사항 (Limitations)

  • 공개 미리보기. AI 함수 평가 및 최적화 기능(FROM SPECIFICATION, EXECUTE EXPERIMENT, DESCRIBE EXPERIMENT)은 공개 미리보기이며 계정에 단계적으로 배포되고 있어요.
  • 실행 가능한 유형만. AI_FUNCTION_EVALUATION 및 AI_FUNCTION_OPTIMIZATION 실험만 실행할 수 있어요.
  • 단일 실행. 실험은 한 번 실행되며, 재실행하려면 새 실험(또는 교체된 실험)이 필요해요.
  • UNDROP 없음. 삭제된 실험은 복원할 수 없어요. UNDROP EXPERIMENT가 없어요.
  • 비동기만. 결과는 EXECUTE EXPERIMENT가 반환하지 않아요. SHOW RUNS / SHOW RUN METRICS / SHOW RUN PARAMETERS로 읽어요.
  • 실행 시간 제한. 실행은 20시간으로 제한되며, 더 긴 실행은 종료돼요.
  • 데이터셋 크기 제한. 참조된 데이터셋은 최대 1,000행을 포함할 수 있어요(약 50–200 권장).

더 알아보기 (Learn more)