create-collection

Milvus 컬렉션 만들기 (Create Collection)

Milvus에 데이터를 넣으려면 먼저 **컬렉션(Collection)**을 만들어야 해요. 컬렉션은 고정된 컬럼과 가변적인 행을 가진 이차원 테이블로, 각 컬럼이 필드(field)이고 각 행이 엔티티(entity)인데, 이 구조를 정의하는 게 **스키마(Schema)**예요. 이 페이지는 소스 문서 Milvus — Create Collection 를 바탕으로, 스키마 정의부터 인덱스 파라미터 설정, 실제 생성까지의 흐름을 설명해요.

컬렉션의 모든 측면 — 스키마, 인덱스 파라미터, 거리 척도, 생성 시 로드 여부 — 을 미리 정해 요구사항에 꼭 맞게 만들 수 있어요. 컬렉션을 만들려면 일반적으로 스키마를 만들고, (선택) 인덱스 파라미터를 설정한 뒤 컬렉션을 생성합니다.

스키마 만들기

스키마는 컬렉션의 데이터 구조를 정의해요. 여러분의 요구사항에 맞춰 설계하며, 모든 삽입 엔티티는 스키마가 정한 제약을 지켜야 합니다.

아래 코드는 동적 필드를 켜고 my_id(INT64, 기본 키), my_vector(FLOAT_VECTOR, 5차원), my_varchar(VARCHAR, 최대 512) 세 필드를 가진 스키마를 만드는 파이썬 예시예요. 스칼라 필드에는 기본값을 주거나 nullable로 만들 수도 있습니다.

from pymilvus import MilvusClient, DataType

client = MilvusClient(uri="http://localhost:19530", token="root:Milvus")

# 3.1. Create schema
schema = MilvusClient.create_schema(
    auto_id=False,
    enable_dynamic_field=True,
)

# 3.2. Add fields to schema
schema.add_field(field_name="my_id", datatype=DataType.INT64, is_primary=True)
schema.add_field(field_name="my_vector", datatype=DataType.FLOAT_VECTOR, dim=5)
schema.add_field(field_name="my_varchar", datatype=DataType.VARCHAR, max_length=512)

필드 타입과 스키마 설계에 관한 자세한 내용은 Schema Explained 를 참고해요.

(선택) 인덱스 파라미터 설정

특정 필드에 인덱스를 만들면 그 필드에 대한 검색이 빨라져요. 인덱스는 컬렉션 안 엔티티의 정렬 순서를 기록합니다. 코드에서 index_type과 metric_type으로 Milvus가 필드를 어떻게 인덱싱하고, 벡터 간 유사도를 어떻게 잴지 정합니다.

Milvus에서 모든 벡터 필드의 인덱스 타입으로 **AUTOINDEX**를 쓸 수 있고, 거리 척도는 상황에 따라 COSINE, L2, IP 중 하나를 고릅니다. 벡터 필드는 인덱스 타입과 거리 척도를 둘 다 설정해야 하고, 스칼라 필드는 인덱스 타입만 설정합니다. 벡터 필드에는 인덱스가 필수이며, 필터 조건에 자주 쓰는 스칼라 필드에도 인덱스를 만들길 권합니다.

# 3.3. Prepare index parameters
index_params = client.prepare_index_params()

# 3.4. Add indexes
index_params.add_index(field_name="my_id", index_type="AUTOINDEX")
index_params.add_index(field_name="my_vector", index_type="AUTOINDEX", metric_type="COSINE")

컬렉션 생성

인덱스 파라미터와 함께 컬렉션을 만들면 Milvus가 생성 시점에 컬렉션을 자동 로드합니다. 이 경우 인덱스 파라미터에 언급된 모든 필드가 인덱싱되죠.

# 3.5. Create a collection with the index loaded simultaneously
client.create_collection(
    collection_name="customized_setup_1",
    schema=schema,
    index_params=index_params,
)
res = client.get_load_state(collection_name="customized_setup_1")
print(res)  # {'state': '<LoadState: Loaded>'}

반대로 인덱스 파라미터 없이 컬렉션을 만들면 생성 시점에 로드되지 않고, 이후 인덱스를 추가하면 그때 로드가 진행돼요. 인덱스 없이 만들 때의 로드 상태는 unloaded로 남습니다.

RESTful API로 만들 수도 있어요.

export CLUSTER_ENDPOINT="http://localhost:19530"
export TOKEN="root:Milvus"

curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/collections/create" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
--header "Request-Timeout: 10" \
-d '{
    "collectionName": "customized_setup_1",
    "schema": $schema,
    "indexParams": $indexParams
}'

그 외 설정: TTL, 일관성 수준, 동적 필드

TTL 설정

컬렉션에 TTL(Time To Live)을 걸면 만료된 엔티티가 자동으로 삭제·공간에서 해제돼요. 아래는 TTL을 하루(86400초)로 설정한 예시인데, 가이드상 최소 며칠 단위를 권장합니다.

client.create_collection(
    collection_name="customized_setup_5",
    schema=schema,
    properties={"collection.ttl.seconds": 86400},
)

일관성 수준 설정

컬렉션 생성 시, 그리고 특정 검색·쿼리 시점에 일관성 수준(consistency level)을 지정할 수 있어요. 예시로 "Bounded"를 씁니다.

client.create_collection(
    collection_name="customized_setup_6",
    schema=schema,
    consistency_level="Bounded",
)

일관성 수준에 대한 자세한 내용은 Consistency Level 을 참고해요.

동적 필드(Dynamic Field) 활성화

동적 필드는 컬렉션에 예약된 JSON 필드인 **$meta**예요. 이 필드를 활성화하면 스키마에 정의되지 않은 필드가 엔티티에 실려 왔을 때, 그 필드와 값을 키-값 쌍으로 $meta에 저장합니다. 스키마를 바꾸지 않고도 유연하게 필드를 추가할 수 있게 해주는 기능이에요.

실제 적용 (데이터스케쳐스)

  • 스키마 우선 설계 — 벡터 필드(차원)와 스칼라 필드를 스키마로 미리 정의해 구조적으로 관리합니다.
  • AUTOINDEX + 거리 척도 — 벡터 필드에 AUTOINDEX를 쓰고 임베딩 모델에 맞춰 COSINE 같은 거리 척도를 지정합니다.
  • 동적 필드 활용 — 문서 메타데이터가 자주 늘어나는 경우 $meta 동적 필드로 스키마 수정 없이 수용합니다.

더 알아보기