기본 컬렉션 조작

기본 컬렉션 조작 (Basic collection operations)

Weaviate에 저장되는 모든 객체는 정확히 하나의 컬렉션에 속해요. 컬렉션을 어떻게 만들고 조회하고 고치고 지우는지, 그 기본기를 이 페이지에서 익힐 수 있습니다. 처음엔 이름만 주고 컬렉션을 만드는 것부터 시작하지만, 실제 운영에서는 속성을 명시적으로 정의하는 쪽이 훨씬 안전합니다.

출처: 공식문서 - Basic collection operations

용어와 대문자 규칙

새 Weaviate 문서는 "컬렉션(collection)"이라는 표현을 쓰고, 예전 문서는 "클래스(class)"라고 불러요. 둘은 같은 것을 가리킵니다. Weaviate는 GraphQL 명명 규칙을 따르므로 컬렉션 이름은 대문자로, 속성 이름은 소문자로 시작해야 합니다. 속성 이름을 대문자로 시작해 정의하면 Weaviate가 내부적으로 소문자로 바꿔버립니다.

컬렉션 만들기

컬렉션을 만들 땐 최소한 이름을 지정해야 합니다. 속성을 지정하지 않으면 auto-schema가 알아서 만들어줍니다.

client.collections.create("Article")

속성과 함께 만들기

속성은 컬렉션의 데이터 필드이며 각각 이름과 데이터 타입을 가집니다.

from weaviate.classes.config import Property, DataType

# v3 클라이언트 스타일 JSON 객체로 컬렉션을 만들려면 client.collections.create_from_dict()를 쓸 수 있어요
client.collections.create(
    "Article",
    properties=[
        Property(name="title", data_type=DataType.TEXT),
        Property(name="body", data_type=DataType.TEXT),
    ],
)

벡터라이저 지정

객체를 만들고 벡터 검색을 실행할 때 벡터 임베딩을 생성할 vectorizer를 지정할 수 있습니다. 단, Python 클라이언트 4.16.0~4.16.3에서 Configure.Vectors.text2vec_xxx()로 속성 없이 컬렉션을 정의하면 vectorize_collection_name을 True로 두지 않으면 오류가 나요. 이 문제는 4.16.4에서 해결됐습니다. 자세한 내용은 Faq의 해당 항목을 참고하세요.

from weaviate.classes.config import Configure, Property, DataType

client.collections.create(
    "Article",
    vector_config=Configure.Vectors.text2vec_openai(),
    properties=[
        Property(name="title", data_type=DataType.TEXT),
        Property(name="body", data_type=DataType.TEXT),
    ],
)

운영 환경을 위한 컬렉션 노하우

데이터 스키마는 수동으로 정의하세요 — auto-schema 대신 컬렉션 속성을 직접 정의하는 편이 좋습니다.
컬렉션을 너무 많이 만들지 마세요 — 컬렉션이 많아지면 메모리 사용량이 늘고 쿼리 성능이 떨어지는 확장성 문제가 생길 수 있어요. 대신 한 컬렉션을 여러 테넌트로 나누는 멀티테넌시를 고려하세요.

컬렉션 존재 확인 · 조회

컬렉션이 존재하는지 불리언으로 확인하거나, 정의를 꺼내볼 수 있습니다.

exists = client.collections.exists("Article")  # 불리언 반환

articles = client.collections.use("Article")
articles_config = articles.config.get()
print(articles_config)

모든 컬렉션 정의를 가져오려면 스키마 전체를 조회하면 됩니다.

response = client.collections.list_all(simple=False)
print(response)

컬렉션 정의 변경

컬렉션 정의를 변경해 변경 가능한(mutable) 컬렉션 설정을 수정할 수 있습니다. 단, 복제 인자(replication factor)는 컬렉션 정의를 수정하는 방식으로는 바꿀 수 없어요 — v1.32부터는 replica movement로 샤드의 복제 인자를 변경할 수 있습니다.

from weaviate.classes.config import (
    Reconfigure,
    VectorFilterStrategy,
    ReplicationDeletionStrategy,
)

articles = client.collections.use("Article")

# 컬렉션 정의 업데이트
articles.config.update(
    description="An updated collection description.",
    property_descriptions={
        "title": "The updated title description for article",
    },  # Weaviate v1.31.0부터 사용 가능
    inverted_index_config=Reconfigure.inverted_index(bm25_k1=1.5),
    vector_config=Reconfigure.Vectors.update(
        name="default",
        vector_index_config=Reconfigure.VectorIndex.hnsw(
            filter_strategy=VectorFilterStrategy.ACORN  # Weaviate v1.27.0부터 사용 가능
        ),
    ),
    replication_config=Reconfigure.replication(
        deletion_strategy=ReplicationDeletionStrategy.TIME_BASED_RESOLUTION  # Weaviate v1.28.0부터 사용 가능
    ),
)

컬렉션 삭제

삭제는 신중해야 해요. 컬렉션을 지우면 그 안의 모든 객체도 함께 삭제됩니다. 프로덕션 데이터베이스에선 특히 조심해야 합니다.

# collection_name은 문자열("Article")이나 문자열 리스트(["Article", "Category"])일 수 있어요
client.collections.delete(
    collection_name
)  # 지정한 컬렉션(들)과 그 객체들을 삭제합니다

# 참고: Weaviate 인스턴스의 모든 컬렉션을 지우려면 client.collections.delete_all()을 쓰세요

데이터 임포트 후 인덱싱 제한

컬렉션 속성을 데이터 임포트 전에 다 추가해두면 인덱스 관련 제한이 없습니다. 반대로 임포트한 뒤에 새 속성을 추가하면 인덱싱에 영향이 있습니다.

속성 인덱스는 임포트 시점에 만들어져요. 이미 데이터를 임포트한 뒤 새 속성을 추가하면, 기존 객체들은 새 속성 인덱스에 자동으로 포함되지 않습니다. 그래서 쿼리 결과가 예상과 다를 수 있어요 — 인덱스가 새 객체만 담고 있기 때문이죠. 컬렉션의 모든 객체를 포함하는 인덱스를 만들려면:

새 컬렉션 — 객체를 임포트하기 전에 컬렉션 속성을 모두 추가하세요.
기존 컬렉션 — 데이터를 내보낸 뒤, 새 속성으로 컬렉션을 다시 만들고 갱신된 컬렉션으로 데이터를 다시 임포트하세요.

속성을 추가한 뒤 데이터를 재인덱싱하는 API는 아직 만들고 있는 중이라 향후 릴리스에서 사용할 수 있습니다.

from weaviate.classes.config import Property, DataType

articles = client.collections.use("Article")

articles.config.add_property(Property(name="onHomepage", data_type=DataType.BOOL))

기본 컬렉션 조작