Lance 확장

Lance 확장 (Lance Extension)

lance 확장은 Lance 테이블 읽기와 쓰기 지원을 추가해요. Lance는 네이티브 클라우드 스토리지 지원과 함께 ML/AI 워크로드에 최적화된 현대적인 레이크하우스 형식이에요.

출처: 문서

본문

설치하고 로드하기 (Installing and Loading)

DuckDB의 core 확장 저장소에서 lance 확장을 설치하고 다음 명령으로 로드할 수 있어요.

INSTALL lance;
LOAD lance;

사용법 (Usage)

Lance 데이터셋 쿼리하기 (Query a Lance Dataset)

로컬 파일:

SELECT *
FROM '⟨path/to/dataset.lance⟩'
LIMIT 10;

S3:

SELECT *
FROM 's3://⟨bucket/path/to/out.lance⟩'
LIMIT 10;

객체 스토어 URI(예: s3://...)에 접근하려면 Secrets Manager로 TYPE lance secret을 구성해요.

CREATE SECRET (
    TYPE lance,
    PROVIDER credential_chain,
    SCOPE 's3://bucket/'
);

SELECT *
FROM 's3://⟨bucket/path/to/out.lance⟩'
LIMIT 10;

Lance 데이터셋 쓰기 (Write a Lance Dataset)

COPY ... TO ... 문을 사용해 쿼리 결과를 Lance 데이터셋으로 구체화해요.

-- Create/overwrite a Lance dataset from a query
COPY (
    SELECT 1::BIGINT AS id, 'a'::VARCHAR AS s
    UNION ALL
    SELECT 2::BIGINT AS id, 'b'::VARCHAR AS s
) TO '⟨path/to/dataset.lance⟩' (
    FORMAT lance,
    MODE 'overwrite'
);

-- Read it back via the replacement scan
SELECT count(*) FROM '⟨path/to/dataset.lance⟩';

-- Append more rows to an existing dataset
COPY (
    SELECT 3::BIGINT AS id, 'c'::VARCHAR AS s
) TO '⟨path/to/dataset.lance⟩' (
    FORMAT lance,
    MODE 'append'
);

-- Optionally create an empty dataset (schema only)
COPY (
    SELECT 1::BIGINT AS id, 'x'::VARCHAR AS s
    WITH NO DATA
) TO 'path/to/empty.lance' (
    FORMAT lance,
    MODE 'overwrite',
    WRITE_EMPTY_FILE true
);

s3://... 경로에 쓰려면 Secrets Manager로 그 스코프에 TYPE lance secret을 구성해요.

CREATE SECRET (
    TYPE lance,
    PROVIDER credential_chain,
    SCOPE 's3://⟨bucket⟩/'
);

COPY (SELECT 1 AS id)
TO 's3://⟨bucket/path/to/out.lance⟩'
(FORMAT lance, MODE 'overwrite');

`CREATE TABLE`로 Lance 데이터셋 만들기 (디렉터리 네임스페이스)

디렉터리를 Lance 네임스페이스로 ATTACH하면 CREATE TABLE(스키마만) 또는 CREATE TABLE AS SELECT (CTAS)로 새 데이터셋을 만들 수 있어요. 데이터셋은 ⟨namespace_root⟩/⟨table_name.lance⟩에 기록돼요.

ATTACH '⟨path/to/dir⟩' AS lance_ns (TYPE lance);

-- Schema-only (creates an empty dataset)
CREATE TABLE lance_ns.main.my_empty (id BIGINT, s VARCHAR);

-- CTAS (writes query results)
CREATE TABLE lance_ns.main.my_dataset AS
    SELECT 1::BIGINT AS id, 'a'::VARCHAR AS s
    UNION ALL
    SELECT 2::BIGINT AS id, 'b'::VARCHAR AS s;

SELECT count(*) FROM lance_ns.main.my_dataset;

벡터 검색 (Vector Search)

-- Search a vector column, returning distances in `_distance` (smaller is closer)
SELECT id, label, _distance
FROM lance_vector_search(
    '⟨path/to/dataset.lance⟩', 'vec',
    [0.1, 0.2, 0.3, 0.4]::FLOAT[4],
    k = 5,
    prefilter = true
)
ORDER BY _distance ASC;

전체 파라미터 문서는 SQL 참조를 참고해요.

전문 검색 (Full-Text Search / FTS)

-- Search a text column, returning BM25-like scores in `_score`
SELECT id, text, _score
FROM lance_fts(
    '⟨path/to/dataset.lance⟩',
    'text',
    'puppy',
    k = 10,
    prefilter = true
)
ORDER BY _score DESC;