컬렉션 별칭

컬렉션 별칭 (Collection aliases)

컬렉션을 새 스키마로 바꿔야 하는데 다운타임을 견딜 수 없다면, **별칭(Alias)**이 정답이에요. 별칭은 컬렉션의 대체 이름을 만들어주고, 애플리케이션 코드는 그대로 둔 채 요청을 다른 컬렉션으로 돌릴 수 있습니다. 무중단 마이그레이션이나 A/B 테스트, 혹은 더 편한 이름을 붙이고 싶을 때 유용하죠.

별칭은 컬렉션을 가리키는 참조 역할을 합니다 — 별칭 이름으로 객체를 쿼리하거나 관리하면 Weaviate가 자동으로 대상 컬렉션으로 요청을 라우팅해요.

출처: 공식문서 - Collection aliases

별칭 만들기

별칭을 만들려면 별칭 이름과 그것이 가리킬 대상 컬렉션을 지정합니다.

# 먼저 컬렉션을 만듭니다
client.collections.create(
    name="Articles",
    vector_config=wvc.config.Configure.Vectors.self_provided(),
    properties=[
        wvc.config.Property(name="title", data_type=wvc.config.DataType.TEXT),
        wvc.config.Property(name="content", data_type=wvc.config.DataType.TEXT),
    ],
)

# 컬렉션을 가리키는 별칭 만들기
client.alias.create(alias_name="ArticlesAlias", target_collection="Articles")

별칭 규칙 — 별칭 이름은 고유해야 하며 기존 컬렉션·별칭 이름과 겹칠 수 없습니다. 여러 별칭이 같은 컬렉션을 가리킬 수 있어요. 별칭은 객체 관련 작업(객체 관리와 쿼리)에서만 컬렉션 이름 대신 사용할 수 있습니다.

별칭 목록 조회

인스턴스의 모든 별칭을 가져옵니다.

# 인스턴스의 모든 별칭 가져오기
all_aliases = client.alias.list_all()

for alias_name, alias_info in all_aliases.items():
    print(f"Alias: {alias_info.alias} -> Collection: {alias_info.collection}")

특정 컬렉션을 가리키는 별칭만 조회할 수도 있습니다.

# 특정 컬렉션을 가리키는 모든 별칭 가져오기
collection_aliases = client.alias.list_all(collection="Articles")

for alias_name, alias_info in collection_aliases.items():
    print(f"Alias pointing to Articles: {alias_info.alias}")

별칭 상세 조회

특정 별칭에 대한 정보를 가져옵니다.

# 특정 별칭에 대한 정보 가져오기
alias_info = client.alias.get(alias_name="ArticlesAlias")

if alias_info:
    print(f"Alias: {alias_info.alias}")
    print(f"Target collection: {alias_info.collection}")

별칭 업데이트(대상 변경)

별칭이 가리키는 대상 컬렉션을 바꿉니다. 이 작업은 **원자적(atomic)**이라 컬렉션 간 즉시 전환이 가능합니다.

# 마이그레이션을 위한 새 컬렉션 만들기
client.collections.create(
    name="ArticlesV2",
    vector_config=wvc.config.Configure.Vectors.self_provided(),
    properties=[
        wvc.config.Property(name="title", data_type=wvc.config.DataType.TEXT),
        wvc.config.Property(name="content", data_type=wvc.config.DataType.TEXT),
        wvc.config.Property(
            name="author", data_type=wvc.config.DataType.TEXT
        ),  # 새 필드
    ],
)

# 별칭을 새 컬렉션으로 업데이트
success = client.alias.update(
    alias_name="ArticlesAlias", new_target_collection="ArticlesV2"
)

if success:
    print("Alias updated successfully")

활용: 무중단 마이그레이션 — 별칭 업데이트는 마이그레이션에 특히 유용합니다.

갱신된 컬렉션 정의로 새 컬렉션을 만든다

새 컬렉션으로 데이터를 임포트한다

별칭을 새 컬렉션을 가리키도록 업데이트한다

계속 별칭을 사용한다 — 별칭으로 가는 모든 쿼리가 이제 새 컬렉션으로 향한다

코드 예시는 Tutorial: Migrating collections with aliases에서 볼 수 있습니다.

별칭 삭제

별칭을 제거합니다. 이건 별칭 포인터만 삭제하지 기반 컬렉션은 그대로 둡니다.

# 별칭 삭제 (기반 컬렉션은 남아있습니다)
client.alias.delete(alias_name="ArticlesAlias")

참고 — 컬렉션을 삭제해도 그 컬렉션을 가리키는 별칭은 자동으로 삭제되지 않습니다.

작업에서 별칭 사용하기

만들어진 별칭은 데이터 임포트와 쿼리처럼 객체 관련 작업에서 컬렉션 이름 대신 사용할 수 있어요. 다음은 마이그레이션 전 과정을 별칭으로 이어지는 예시입니다.

1) 원본 컬렉션 생성

# 데이터가 있는 원본 컬렉션 만들기
client.collections.create(
    name="Products_v1", vector_config=wvc.config.Configure.Vectors.self_provided()
)

products_v1 = client.collections.use("Products_v1")
products_v1.data.insert_many(
    [{"name": "Product A", "price": 100}, {"name": "Product B", "price": 200}]
)

2) 현재 컬렉션을 가리키는 별칭 생성

# 현재 컬렉션을 가리키는 별칭 만들기
client.alias.create(alias_name="ProductsAlias", target_collection="Products_v1")

3) 애플리케이션은 별칭만 사용

# 애플리케이션은 항상 별칭 이름 "Products"를 사용합니다
products = client.collections.use("ProductsAlias")

# 별칭을 통해 데이터 삽입
products.data.insert({"name": "Product C", "price": 300})

# 별칭을 통해 쿼리
results = products.query.fetch_objects(limit=5)
for obj in results.objects:
    print(f"Product: {obj.properties['name']}, Price: ${obj.properties['price']}")

4) 새 스키마 컬렉션 생성

# 갱신된 스키마로 새 컬렉션 만들기
client.collections.create(
    name="Products_v2",
    vector_config=wvc.config.Configure.Vectors.self_provided(),
    properties=[
        wvc.config.Property(name="name", data_type=wvc.config.DataType.TEXT),
        wvc.config.Property(name="price", data_type=wvc.config.DataType.NUMBER),
        wvc.config.Property(
            name="category", data_type=wvc.config.DataType.TEXT
        ),  # 새 필드
    ],
)

5) 데이터 마이그레이션

# 새 컬렉션으로 데이터 마이그레이션
products_v2 = client.collections.use("Products_v2")
old_data = products_v1.query.fetch_objects().objects

for obj in old_data:
    products_v2.data.insert(
        {
            "name": obj.properties["name"],
            "price": obj.properties["price"],
            "category": "General",  # 새 필드의 기본값
        }
    )

6) 별칭 전환과 정리

# 별칭을 새 컬렉션으로 전환 (즉시 전환!)
client.alias.update(alias_name="ProductsAlias", new_target_collection="Products_v2")

# "Products" 별칭을 쓰는 모든 쿼리는 이제 새 컬렉션을 사용합니다
products = client.collections.use("ProductsAlias")
result = products.query.fetch_objects(limit=1)
print(result.objects[0].properties)  # 새 "category" 필드가 포함됩니다

# 검증 후 옛 컬렉션 정리
client.collections.delete("Products_v1")

컬렉션 별칭