네임스페이스 관리하기

네임스페이스(Namespace)는 인덱스 안에서 레코드를 논리적으로 나누는 파티션이에요. 고객별로 데이터를 격리하거나, 쿼리가 한 파티션만 스캔하게 만들어 성능을 높이는 데 써요. 이 문서에서는 네임스페이스를 만들고, 목록을 조회하고, 삭제하는 방법을 각각 살펴볼게요. 특히 API 버전과 삭제의 비가역성 같은 실전에서 자주 마주치는 부분을 짚어볼게요.

출처: Manage namespaces (공식 문서)

네임스페이스 만들기

네임스페이스는 레코드를 업서트하면 자동으로 생겨요. 하지만 create_namespace 연산으로 미리 만들 수도 있는데, 이 기능은 API 2025-10 버전에서만 사용할 수 있어요. 미리 만들 때는 네임스페이스 이름과, 선택적으로 인덱싱할 메타데이터 필드를 지정할 수 있어요. 네임스페이스에 아직 데이터가 없어도 검색·필터링에 쓸 메타데이터 필드 스키마를 선언해두는 셈이에요.

Python SDK로는 pc.Index(host=...)로 인덱스를 연결한 뒤 create_namespace를 호출해요. 인덱스의 고유 호스트(host)는 target-an-index 문서에서 확인할 수 있어요.

from pinecone import Pinecone

pc = Pinecone(api_key="YOUR_API_KEY")

index = pc.Index(host="INDEX_HOST")

namespace = index.create_namespace(
    name="example-namespace",
    schema={
        "fields": {
            "document_id": {"filterable": True},
            "document_title": {"filterable": True},
            "chunk_number": {"filterable": True},
            "document_url": {"filterable": True},
            "created_at": {"filterable": True}
        }
    }
)

print(namespace)

curl로는 호스트 경로의 /namespaces에 POST를 보내고, X-Pinecone-Api-Version: 2025-10 헤더를 함께 보내요. 필터링할 메타데이터 필드마다 "filterable": true를 지정한 것이 보이죠. 이렇게 미리 필터 가능 필드를 선언해두면 이후 업서트·검색 코드가 깔끔해져요.

인덱스의 모든 네임스페이스 목록 조회

list_namespaces 연산으로 서버리스 인덱스의 모든 네임스페이스를 나열할 수 있어요. 기본적으로 한 번에 최대 100개가 정렬된 순서(bitwise "C" collation)로 반환돼요. limit 파라미터를 주면 그만큼만 반환하고, 반환할 네임스페이스가 더 남으면 응답에 pagination_token이 포함돼서 다음 배치를 가져올 수 있어요. pagination_token이 응답에 없으면 더 이상 반환할 네임스페이스가 없다는 뜻이에요.

Python SDK에서는 제너레이터 함수를 쓰는 암시적 페이지네이션과, 토큰을 직접 넘기는 수동 페이지네이션을 모두 지원해요.

from pinecone import Pinecone

pc = Pinecone(api_key="YOUR_API_KEY")

index = pc.Index(host="INDEX_HOST")

# 암시적 페이지네이션 (제너레이터 함수)
for namespace in index.list_namespaces():
    print(namespace.name, ":", namespace.record_count)

# 수동 페이지네이션
namespaces = index.list_namespaces_paginated(
    limit=2,
    pagination_token="eyJza2lwX3Bhc3QiOiIxMDEwMy0="
)

print(namespaces)

네임스페이스 삭제

delete_namespace 연산으로 서버리스 인덱스의 네임스페이스를 삭제할 수 있어요. 주의할 점은 네임스페이스 삭제는 되돌릴 수 없어요. 그 네임스페이스의 모든 데이터가 영구 삭제돼요. curl로는 호스트 경로의 /namespaces/<namespace>에 DELETE를 보내요. 기본 네임스페이스를 대상으로 하려면 __default__를 사용해요.

PINECONE_API_KEY="YOUR_API_KEY"
INDEX_HOST="INDEX_HOST"
NAMESPACE="NAMESPACE_NAME" # 기본 네임스페이스를 대상으로 하려면 "__default__"를 사용

curl -X DELETE "https://$INDEX_HOST/namespaces/$NAMESPACE" \
    -H "Api-Key: $PINECONE_API_KEY" \
    -H "X-Pinecone-Api-Version: 2025-10"

네임스페이스 이름 바꾸기 / 레코드 옮기기

Pinecone은 네임스페이스 이름을 직접 바꾸는 것을 지원하지 않아요. 대신 원래 네임스페이스의 레코드를 삭제(delete-data)하고, 새 네임스페이스에 레코드를 업서트(upsert-data)하면 돼요. 네임스페이스 간에 레코드를 직접 옮기는 것도 지원하지 않아서, 마찬가지로 기존 네임스페이스에서 지우고 새 네임스페이스에 다시 넣는 과정을 거쳐야 해요. 이 방법은 멀티테넌트 구조에서 테넌트를 재편할 때 유용하지만, 이동 중 데이터가 잠시 사라질 수 있으니 계획을 잘 세워야 해요.

네임스페이스 관리하기