데이터 객체

에이전트 검색 (이전 명칭: Vector Search 2.0)에서 컬렉션은 데이터 객체라는 개별 JSON 객체로 데이터를 저장합니다. 이 페이지에서는 데이터 객체가 충족해야 하는 유효성 검사 규칙과 데이터 객체를 개별적으로 또는 일괄적으로 생성, 읽기, 업데이트, 가져오기, 내보내기, 삭제하는 방법을 설명합니다.

데이터 검증

에이전트 검색에서 인그레션하는 모든 데이터 객체는 고정된 규칙 집합에 대해 검사됩니다. 레코드에 대해 규칙이 실패하면 해당 레코드가 거부되고 code = INVALID_ARGUMENT와 함께 오류 싱크로 전송됩니다. 이후 검사는 해당 레코드에 대해 실행되지 않습니다. '오류 하나를 수정하고 다시 수집한 후 다음 오류가 발생하는' 루프를 방지하려면 수집 또는 색인 빌드를 시작하기 전에 데이터 유효성 검사 규칙 전체에 대해 데이터 세트를 검증하세요.

파이프라인은 다음 순서로 유효성 검사를 적용합니다.

단계 확인 사항
1. 파싱 JSON 형식이 올바르고, 필수 최상위 필드가 있으며, 필드 유형이 올바릅니다.
2. ID 유효성 검사 id 필드가 있고 문서화된 ID 형식과 일치합니다.
3. 데이터 필드 스키마 data 페이로드는 컬렉션의 CollectionConfig에 선언된 JSON 스키마를 준수합니다.
4. 임베딩 유효성 검사 각 밀도/희소 벡터는 컬렉션의 벡터 스키마 (이름, 유형, 차원, 유한 값, 희소 패리티 및 고유성)와 일치합니다.
5. 검색 가능한 필드 채우기 스키마에서 검색 가능으로 표시된 필드를 data에서 추출할 수 있음

1. 파싱 유효성 검사

파싱 유효성 검사는 각 입력 행을 내부 데이터 객체로 변환하는 동안 먼저 실행됩니다. 이러한 규칙은 지원되는 JSON 모양인 기본 형식 (최상위 vectors/data 객체 포함)과 v1 형식 (embedding, sparse_embedding, restricts 또는 numeric_restricts 포함) 모두에 적용됩니다. 형식은 레코드별로 자동 감지됩니다.

  • JSON을 파싱할 수 있어야 합니다. 각 줄은 JSON 객체로 파싱되어야 합니다. 최상위 키가 기본 형식과 v1 형식 모두와 일치하지 않는 행은 Unknown JSON format for string: <line>로 거부됩니다.
  • id이 필수입니다. 모든 레코드에는 null이 아닌 id이 포함되어야 합니다. 그렇지 않으면 'id' field is missing or null이 발생합니다.
  • 삽입이 있어야 합니다 (v1 형식만 해당). v1 형식 레코드에는 embedding 또는 sparse_embedding 중 하나 이상이 포함되어야 합니다. 그 외의 경우: 'embedding' or 'sparse_embedding' fields are missing
  • 밀집 임베딩 유형 검사 밀도 있는 삽입 필드 (v1의 embedding 또는 기본 형식의 vectors 아래의 배열 값)는 숫자의 JSON 배열이어야 합니다. float로 강제 변환할 수 없는 값은 '<field>' field contains non-float values로 거부됩니다.
  • 희소 임베딩 구조 확인 모든 희소 벡터에 대해 다음을 수행합니다.
    • JSON 객체여야 합니다.
    • values (부동 소수점) 및 indices (long) 배열을 모두 포함해야 합니다. v1에서는 values 및 dimensions입니다.
    • values은(는) 비워 둘 수 없습니다.
    • 색인은 음수가 아니어야 합니다.
    • values.length는 indices.length (또는 v1 dimensions.length)와 같아야 합니다.
  • data 필드 유형 data이 있는 경우 배열, 문자열 또는 스칼라가 아닌 JSON 객체여야 합니다. 그 외의 경우: 'data' field is not a JSON object
  • numeric_restricts 모양 (v1 형식) numeric_restricts은 객체의 JSON 배열이어야 합니다. 각 항목에는 문자열 namespace이 있어야 하며 value_int, value_float 또는 value_double 중 하나만 설정해야 합니다.

대부분의 '첫 번째 실패' 문제는 이 단계에서 발생합니다. 일반적인 오류로는 삽입 배열의 문자열화된 숫자, 누락된 id, 길이가 다른 values/indices 등이 있습니다.

2. ID 유효성 검사

데이터 객체 ID는 RFC 1035를 준수해야 합니다. 실제로 이는 다음을 의미합니다.

  • 1~63자(영문 기준)여야 합니다.
  • 소문자, 숫자, 하이픈 (-)만 사용하세요. 대문자, 밑줄, 공백, 기호, 유니코드는 사용할 수 없습니다.
  • 소문자로 시작해야 합니다 (a-z).
  • 소문자 또는 숫자로 끝나야 합니다 (-로 끝나면 안 됨).

정규 표현식: [a-z]([-a-z0-9]{0,61}[a-z0-9])?

다음 표에는 일반적인 예가 나와 있습니다.

ID 유효한가? 이유
doc-123 예 문자로 시작하고 소문자, 숫자, 하이픈만 사용하며 숫자로 끝남
a 예 최소한 하나의 소문자가 필요합니다.
product-sku-42 예 모든 규칙 충족
Doc-123 아니요 대문자 D는 허용되지 않음
123-doc 아니요 숫자가 아닌 문자로 시작해야 합니다.
doc_123 아니요 밑줄이 허용되지 않음
doc-123- 아니요 하이픈으로 끝나면 안 됩니다.
my doc 아니요 공백은 허용되지 않음
64자 이상 아니요 최대 길이는 63입니다.

이 모양은 DNS 라벨 규칙 (my-service.example.com과 같은 호스트 이름에서 점 사이의 부분)입니다. 이 모양은 이스케이프 없이 URL, 파일 이름, 로그, CLI를 통해 ID가 안전하게 왕복할 수 있도록 여기에서 재사용됩니다.

3. 데이터 필드 검증 (JSON 스키마)

데이터 필드 유효성 검사 단계는 컬렉션의 CollectionConfig에 dataSchema가 선언된 경우에만 실행됩니다. 스키마가 구성되지 않은 경우 이 단계는 건너뜁니다.

  • 스키마 준수. 데이터 객체의 data 페이로드가 JSON으로 직렬화되고 구성된 JSON 스키마 (초안 7)에 대해 검증됩니다. 검증기는 스키마 위반당 하나의 오류를 보고하므로 잘못된 필드가 3개인 레코드는 오류 메시지 3개를 생성합니다.
    • 메시지: DataObject with id <id> failed schema validation: <error>
  • 스키마 처리 오류. 스키마 유효성 검사기 자체에서 예외를 발생시키는 경우 (예: 지원되지 않는 초안 기능) 레코드가 DataObject with id <id> failed schema validation processing: <exception>로 거부됩니다.

4. 임베딩 필드 유효성 검사

임베딩 필드 유효성 검사 단계에서는 먼저 밀집 벡터를 반복한 다음 희소 벡터를 반복합니다. 확인된 벡터 이름의 단일 공유 집합은 두 목록에 모두 적용되므로 이름은 밀도와 희소성 경계를 포함하여 두 번 사용할 수 없습니다.

공유 규칙 (밀도와 희소성에 모두 적용)

규칙 중요한 이유 오류 메시지
동일한 데이터 객체의 밀도와 희소성에서 중복된 벡터 이름이 없음 벡터 이름이 동일한 두 항목은 동일한 저장소 키를 타겟팅하여 마지막 쓰기 우선 동작이 정의되지 않습니다. ... has duplicate embedding field '<name>' across its dense/sparse vectors; each vector name must appear at most once
CollectionConfig 벡터 스키마에서 벡터 이름을 선언해야 합니다. 알 수 없는 벡터 이름은 열로 라우팅할 수 없습니다. ... has dense/sparse embedding field '<name>' but this field is not defined in CollectionConfig vector schema

밀도 벡터 전용 규칙

규칙 오류 메시지
필드는 컬렉션 스키마에서 dense로 구성되어야 합니다. ... has dense embedding field '<name>' but CollectionConfig defines it as non-dense
측정기준이 구성된 측정기준과 일치해야 합니다. ... field '<name>': expected dense embedding dimension <expected>, but got <actual>
모든 값은 유한해야 합니다. NaN, +Infinity 또는 -Infinity은 허용되지 않습니다. 무한 값이 있으면 거리 계산이 손상됩니다. ... field '<name>': dense embedding contains non-finite value <v> at index <i> (NaN/Infinity values are not allowed)

희소 벡터 전용 규칙

규칙 오류 메시지
필드는 컬렉션 스키마에서 sparse로 구성되어야 합니다. ... has sparse embedding field '<name>' but CollectionConfig defines it as non-sparse
색인/값 길이 패리티: indicesCount == valuesCount. ... field '<name>': sparse embedding has <n> indices but <m> values; indices and values must have the same length
비음수 색인: 모든 색인이 0 이상입니다. ... field '<name>': sparse embedding contains negative index <i> at position <p> (indices must be non-negative)
동일한 희소 벡터 내의 고유한 색인 ... field '<name>': sparse embedding contains duplicate index <i> (each index must appear at most once)
모든 값은 유한해야 합니다. ... field '<name>': sparse embedding contains non-finite value <v> at position <p> (NaN/Infinity values are not allowed)

5. 검색 가능한 필드 채우기

삽입된 유효성 검사가 성공하면 파이프라인은 컬렉션의 dataSchema를 사용하여 data 페이로드를 탐색하고 스키마에서 선언한 필드 (문자열, 정수/숫자, 불리언, 문자열 배열, 중첩 객체)를 검색 가능한 필드 색인에 복사합니다. 여기서 두 가지 오류 모드도 레코드를 거부합니다.

  • 구조체여야 하는 경로에 스칼라가 포함되어 있습니다 (예: 스키마에 author.name이 문자열이라고 나와 있지만 author 자체가 문서에서 문자열임).
  • 문자열 배열 필드에 문자열이 아닌 요소가 포함되어 있습니다.

이러한 오류는 일반적으로 문서의 모양이 선언된 스키마에서 벗어났음을 나타내며 JSON 스키마 단계에서 항상 포착되는 것은 아닙니다.

사전 체크리스트

수집 또는 색인 빌드를 시작하기 전에 다음 규칙에 따라 전체 데이터 세트를 검증하세요. 이는 파이프라인에서 적용하는 동일한 검사 집합으로, 단일 클라이언트 측 패스가 모든 문제를 표시하도록 정렬됩니다.

  1. 형식 - 모든 줄이 JSON으로 파싱되고 기본 또는 v1 모양과 일치합니다.
  2. ID: RFC 1035 정규 표현식 [a-z]([-a-z0-9]{0,61}[a-z0-9])?와 일치하며 데이터 세트 전체에서 고유합니다.
  3. 임베딩 있음 - 레코드당 벡터가 하나 이상 있습니다. 벡터 이름이 CollectionConfig 벡터 스키마에 올바른 밀도 또는 희소 유형으로 나열됩니다.
  4. 밀도 벡터: 올바른 차원, NaN, +Inf 또는 -Inf 값이 없음
  5. 희소 벡터 -- values.length == indices.length; 0보다 크거나 같고 고유한 모든 색인입니다. 유한하지 않은 값은 허용되지 않습니다.
  6. 밀도와 희소성 전반에 걸쳐 레코드 내에 중복된 벡터 이름이 없음
  7. 데이터 스키마: dataSchema가 구성된 경우 data 페이로드가 이에 대해 검증되고 (초안 7) 모든 필드의 실제 JSON 유형이 선언된 유형과 일치합니다 (특히 중첩된 객체와 문자열 배열의 경우).
  8. v1 numeric_restricts: 모든 항목에 문자열 namespace이 있고 value_int / value_float / value_double 중 하나가 정확히 하나 있습니다.

데이터 객체 만들기

다음 예시에서는 ID가 COLLECTION_ID인 컬렉션에 단일 데이터 객체를 추가하는 방법을 보여줍니다.

REST

요청 데이터를 사용하기 전에 다음을 바꿉니다.

  • DATA_OBJECT_ID: 데이터 객체의 ID입니다.
  • COLLECTION_ID: 컬렉션의 ID입니다.
  • LOCATION: Agent Platform을 사용하는 리전입니다.
  • PROJECT_ID: Google Cloud 프로젝트 ID

HTTP 메서드 및 URL: 

POST https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects?dataObjectId=DATA_OBJECT_ID

JSON 요청 본문:

{
  "data": {
    "director": "Frank Darabont",
    "genre": "Drama",
    "title": "The Shawshank Redemption",
    "year": 1994
  },
  "vectors":{
    "genre_embedding": {
      "dense": {
        "values": [ 0.38638010860523064, 0.739343471733759, 0.16189056837017107, 0.5271366865924485 ]
      }
    },
    "plot_embedding": {
      "dense": {
        "values": [ 0.4752082440607731, 0.09026746166854707, 0.8752307753619009 ]
      }
    },
    "soundtrack_embedding": {
      "dense": {
        "values": [ 0.5920451749052875, 0.08301644173787519, 0.1264733498775969, 0.6196429624200321, 0.4925828581737443 ]
      }
    },
    "sparse_embedding": {
      "sparse": {
        "indices": [ 4065, 13326, 17377, 25918, 28105, 32683, 42998 ],
        "values": [ 1, 6, 3, 2, 8, 5, 2 ]
      }
    }
  }
}

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

다음과 비슷한 JSON 응답이 표시됩니다.

{
  "name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/DATA_OBJECT_ID",
  "data": {
    "director": "Frank Darabont",
    "title": "The Shawshank Redemption",
    "year": 1994,
    "genre": "Drama"
  },
  "vectors": {
    "genre_embedding": {
      "dense": {
        "values": [
          0.3863801,
          0.73934346,
          0.16189057,
          0.5271367
        ]
      }
    },
    "plot_embedding": {
      "dense": {
        "values": [
          0.47520825,
          0.090267465,
          0.8752308
        ]
      }
    },
    "soundtrack_embedding": {
      "dense": {
        "values": [
          0.5920452,
          0.08301644,
          0.12647335,
          0.619643,
          0.49258286
        ]
      }
    },
    "sparse_embedding": {
      "sparse": {
        "values": [
          1,
          6,
          3,
          2,
          8,
          5,
          2
        ],
        "indices": [
          4065,
          13326,
          17377,
          25918,
          28105,
          32683,
          42998
        ]
      }
    }
  }
}

gcloud

아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.

  • DATA_FILE: 데이터 객체의 데이터 부분이 포함된 JSON 파일의 로컬 경로입니다.

    파일 콘텐츠의 예:

    {
  "director": "Frank Darabont",
  "genre": "Drama",
  "title": "The Shawshank Redemption",
  "year": 1994
}
  • VECTORS_FILE: 데이터 객체의 벡터 부분이 포함된 JSON 파일의 로컬 경로입니다.

    파일 콘텐츠의 예:

    {
  "genre_embedding": {
    "dense": {
      "values": [ 0.38638010860523064, 0.739343471733759, 0.16189056837017107, 0.5271366865924485 ]
    }
  },
  "plot_embedding": {
    "dense": {
      "values": [ 0.4752082440607731, 0.09026746166854707, 0.8752307753619009 ]
    }
  },
  "soundtrack_embedding": {
    "dense": {
      "values": [ 0.5920451749052875, 0.08301644173787519, 0.1264733498775969, 0.6196429624200321, 0.4925828581737443 ]
    }
  },
  "sparse_embedding": {
    "sparse": {
      "indices": [ 4065, 13326, 17377, 25918, 28105, 32683, 42998 ],
      "values": [ 1, 6, 3, 2, 8, 5, 2 ]
    }
  }
}
  • DATA_OBJECT_ID: 데이터 객체의 ID입니다.
  • COLLECTION_ID: 컬렉션의 ID입니다.
  • LOCATION: Agent Platform을 사용하는 리전입니다.
  • PROJECT_ID: Google Cloud 프로젝트 ID

다음 명령어를 실행합니다.

Linux, macOS 또는 Cloud Shell

gcloud vector-search collections data-objects create DATA_OBJECT_ID \
  --data=DATA_FILE \
  --vectors=VECTORS_FILE \
  --collection=COLLECTION_ID \
  --location=LOCATION \
  --project=PROJECT_ID

Windows(PowerShell)

gcloud vector-search collections data-objects create DATA_OBJECT_ID `
  --data=DATA_FILE `
  --vectors=VECTORS_FILE `
  --collection=COLLECTION_ID `
  --location=LOCATION `
  --project=PROJECT_ID

Windows(cmd.exe)

gcloud vector-search collections data-objects create DATA_OBJECT_ID ^
  --data=DATA_FILE ^
  --vectors=VECTORS_FILE ^
  --collection=COLLECTION_ID ^
  --location=LOCATION ^
  --project=PROJECT_ID

다음과 비슷한 응답이 표시됩니다.

Created dataObject [DATA_OBJECT_ID].

Python

from google.cloud import vectorsearch_v1

# Create the client
data_object_service_client = vectorsearch_v1.DataObjectServiceClient()

# Initialize request
data_object = vectorsearch_v1.DataObject(
    data={
        "title": "The Shawshank Redemption",
        "genre": "Drama",
        "year": 1994,
        "director": "Frank Darabont",
    },
    vectors={
        "plot_embedding": {
            "dense": {"values": [0.1, 0.2, 0.3]}
        },
        "genre_embedding": {
            "dense": {"values": [0.4, 0.5, 0.6, 0.7]}
        },
        "soundtrack_embedding": {
            "dense": {"values": [0.8, 0.9, 1.0, 1.1, 1.2]}
        },
        "sparse_embedding": {
            "sparse": {"values": [1.0, 2.0], "indices": [10, 20]}
        },
    },
)
request = vectorsearch_v1.CreateDataObjectRequest(
    parent="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
    data_object_id="DATA_OBJECT_ID",
    data_object=data_object,
)

# Make the request
response = data_object_service_client.create_data_object(request=request)

# Handle the response
print(response)

컬렉션 스키마에 자동 임베딩이 지정된 임베딩 필드는 자동으로 채워집니다. 자체 임베딩(BYOE)을 가져와 자동으로 채워지지 않는 벡터 필드 값을 설정할 수도 있습니다.

데이터 객체 일괄 생성

소량의 레코드 (요청당 데이터 객체 최대 1,000개)를 효율적으로 대량 수집하려면 batchCreate를 사용하세요. 전체 일괄 처리는 원자적입니다. 모든 데이터 객체가 생성되거나 전체 요청이 실패합니다. 더 큰 데이터 세트의 경우 Cloud Storage에서 데이터 객체를 가져오는 것이 좋습니다.

REST

요청 데이터를 사용하기 전에 다음을 바꿉니다.

  • COLLECTION_ID: 컬렉션의 ID입니다.
  • LOCATION: Agent Platform을 사용하는 리전입니다.
  • PROJECT_ID: Google Cloud 프로젝트 ID

HTTP 메서드 및 URL: 

POST https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:batchCreate

JSON 요청 본문:

{
  "requests": [
    {
      "parent": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
      "dataObjectId": "movie-1",
      "dataObject": {
        "data": {
          "title": "The Shawshank Redemption",
          "year": 1994
        },
        "vectors": {
          "plot_embedding": {
            "dense": { "values": [0.47, 0.09, 0.87] }
          }
        }
      }
    },
    {
      "parent": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
      "dataObjectId": "movie-2",
      "dataObject": {
        "data": {
          "title": "The Godfather",
          "year": 1972
        },
        "vectors": {
          "plot_embedding": {
            "dense": { "values": [0.12, 0.55, 0.31] }
          }
        }
      }
    }
  ]
}

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

다음과 비슷한 JSON 응답이 표시됩니다.

{
  "dataObjects": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-1",
      "data": {
        "title": "The Shawshank Redemption",
        "year": 1994
      },
      "vectors": {
        "plot_embedding": {
          "dense": { "values": [0.47, 0.09, 0.87] }
        }
      }
    },
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-2",
      "data": {
        "title": "The Godfather",
        "year": 1972
      },
      "vectors": {
        "plot_embedding": {
          "dense": { "values": [0.12, 0.55, 0.31] }
        }
      }
    }
  ]
}

gcloud

아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.

  • COLLECTION_ID: 컬렉션의 ID입니다.
  • LOCATION: Agent Platform을 사용하는 리전입니다.
  • PROJECT_ID: Google Cloud 프로젝트 ID

다음 명령어를 실행합니다.

Linux, macOS 또는 Cloud Shell

gcloud vector-search collections data-objects batch-create \
  --collection=COLLECTION_ID \
  --location=LOCATION \
  --project=PROJECT_ID \
  --requests='[
    {
      "parent":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
      "dataObjectId":"movie-1",
      "dataObject":{"data":{"title":"The Shawshank Redemption","year":1994},"vectors":{"plot_embedding":{"dense":{"values":[0.47,0.09,0.87]}}}}
    },
    {
      "parent":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
      "dataObjectId":"movie-2",
      "dataObject":{"data":{"title":"The Godfather","year":1972},"vectors":{"plot_embedding":{"dense":{"values":[0.12,0.55,0.31]}}}}
    }
  ]'

Windows(PowerShell)

gcloud vector-search collections data-objects batch-create `
  --collection=COLLECTION_ID `
  --location=LOCATION `
  --project=PROJECT_ID `
  --requests='[
    {
      "parent":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
      "dataObjectId":"movie-1",
      "dataObject":{"data":{"title":"The Shawshank Redemption","year":1994},"vectors":{"plot_embedding":{"dense":{"values":[0.47,0.09,0.87]}}}}
    },
    {
      "parent":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
      "dataObjectId":"movie-2",
      "dataObject":{"data":{"title":"The Godfather","year":1972},"vectors":{"plot_embedding":{"dense":{"values":[0.12,0.55,0.31]}}}}
    }
  ]'

Windows(cmd.exe)

gcloud vector-search collections data-objects batch-create ^
  --collection=COLLECTION_ID ^
  --location=LOCATION ^
  --project=PROJECT_ID ^
  --requests='[
    {
      "parent":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
      "dataObjectId":"movie-1",
      "dataObject":{"data":{"title":"The Shawshank Redemption","year":1994},"vectors":{"plot_embedding":{"dense":{"values":[0.47,0.09,0.87]}}}}
    },
    {
      "parent":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
      "dataObjectId":"movie-2",
      "dataObject":{"data":{"title":"The Godfather","year":1972},"vectors":{"plot_embedding":{"dense":{"values":[0.12,0.55,0.31]}}}}
    }
  ]'

Python

from google.cloud import vectorsearch_v1

# Create the client
data_object_service_client = vectorsearch_v1.DataObjectServiceClient()

parent = "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID"

# Build per-DataObject create requests.
requests = [
    vectorsearch_v1.CreateDataObjectRequest(
        parent=parent,
        data_object_id="movie-1",
        data_object=vectorsearch_v1.DataObject(
            data={"title": "The Shawshank Redemption", "year": 1994},
            vectors={
                "plot_embedding": {"dense": {"values": [0.47, 0.09, 0.87]}},
            },
        ),
    ),
    vectorsearch_v1.CreateDataObjectRequest(
        parent=parent,
        data_object_id="movie-2",
        data_object=vectorsearch_v1.DataObject(
            data={"title": "The Godfather", "year": 1972},
            vectors={
                "plot_embedding": {"dense": {"values": [0.12, 0.55, 0.31]}},
            },
        ),
    ),
]

request = vectorsearch_v1.BatchCreateDataObjectsRequest(
    parent=parent,
    requests=requests,
)

# Make the request
response = data_object_service_client.batch_create_data_objects(request=request)

# Handle the response
for data_object in response.data_objects:
    print(data_object.name)

데이터 객체 확인

다음 예시에서는 ID가 COLLECTION_ID인 컬렉션에서 ID가 DATA_OBJECT_ID인 데이터 객체를 가져오는 방법을 보여줍니다.

REST

요청 데이터를 사용하기 전에 다음을 바꿉니다.

  • DATA_OBJECT_ID: 데이터 객체의 ID입니다.
  • COLLECTION_ID: 컬렉션의 ID입니다.
  • LOCATION: Agent Platform을 사용하는 리전입니다.
  • PROJECT_ID: Google Cloud 프로젝트 ID

HTTP 메서드 및 URL: 

GET https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/DATA_OBJECT_ID

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

다음과 비슷한 JSON 응답이 표시됩니다.

{
  "name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/DATA_OBJECT_ID",
  "createTime": "2026-01-31T20:05:06Z",
  "updateTime": "2026-01-31T20:05:06Z",
  "data": {
    "title": "The Shawshank Redemption",
    "director": "Frank Darabont",
    "year": 1994,
    "genre": "Drama"
  },
  "vectors": {
    "sparse_embedding": {
      "sparse": {
        "values": [
          1,
          6,
          3,
          2,
          8,
          5,
          2
        ],
        "indices": [
          4065,
          13326,
          17377,
          25918,
          28105,
          32683,
          42998
        ]
      }
    },
    "genre_embedding": {
      "dense": {
        "values": [
          0.3863801,
          0.73934346,
          0.16189057,
          0.5271367
        ]
      }
    },
    "plot_embedding": {
      "dense": {
        "values": [
          0.47520825,
          0.090267465,
          0.8752308
        ]
      }
    },
    "soundtrack_embedding": {
      "dense": {
        "values": [
          0.5920452,
          0.08301644,
          0.12647335,
          0.619643,
          0.49258286
        ]
      }
    }
  }
}

gcloud

아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.

  • DATA_OBJECT_ID: 데이터 객체의 ID입니다.
  • COLLECTION_ID: 컬렉션의 ID입니다.
  • LOCATION: Agent Platform을 사용하는 리전입니다.
  • PROJECT_ID: Google Cloud 프로젝트 ID

다음 명령어를 실행합니다.

Linux, macOS 또는 Cloud Shell

gcloud vector-search collections data-objects describe DATA_OBJECT_ID \
  --collection=COLLECTION_ID \
  --location=LOCATION \
  --project=PROJECT_ID

Windows(PowerShell)

gcloud vector-search collections data-objects describe DATA_OBJECT_ID `
  --collection=COLLECTION_ID `
  --location=LOCATION `
  --project=PROJECT_ID

Windows(cmd.exe)

gcloud vector-search collections data-objects describe DATA_OBJECT_ID ^
  --collection=COLLECTION_ID ^
  --location=LOCATION ^
  --project=PROJECT_ID

다음과 비슷한 응답이 표시됩니다.

name: projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/DATA_OBJECT_ID
data:
  director: Frank Darabont
  genre: Drama
  title: The Shawshank Redemption
  year: 1994
vectors:
  genre_embedding:
    dense:
      values:
      - 0.3863801
      - 0.73934346
      - 0.16189057
      - 0.5271367
  plot_embedding:
    dense:
      values:
      - 0.47520825
      - 0.090267465
      - 0.8752308
  soundtrack_embedding:
    dense:
      values:
      - 0.5920452
      - 0.08301644
      - 0.12647335
      - 0.619643
      - 0.49258286
  sparse_embedding:
    sparse:
      indices:
      - 4065
      - 13326
      - 17377
      - 25918
      - 28105
      - 32683
      - 42998
      values:
      - 1.0
      - 6.0
      - 3.0
      - 2.0
      - 8.0
      - 5.0
      - 2.0

Python

from google.cloud import vectorsearch_v1

# Create the client
data_object_service_client = vectorsearch_v1.DataObjectServiceClient()

# Initialize request
request = vectorsearch_v1.GetDataObjectRequest(
    name="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/DATA_OBJECT_ID",
)

# Make the request
response = data_object_service_client.get_data_object(request=request)

# Handle the response
print(response)

데이터 객체 업데이트

다음 예시에서는 ID가 COLLECTION_ID인 컬렉션에서 ID가 DATA_OBJECT_ID인 데이터 객체의 title 데이터 필드와 plot_embedding 벡터 값을 업데이트하는 방법을 보여줍니다.

REST

요청 데이터를 사용하기 전에 다음을 바꿉니다.

  • DATA_OBJECT_ID: 데이터 객체의 ID입니다.
  • COLLECTION_ID: 컬렉션의 ID입니다.
  • LOCATION: Agent Platform을 사용하는 리전입니다.
  • PROJECT_ID: Google Cloud 프로젝트 ID

HTTP 메서드 및 URL: 

PATCH https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/DATA_OBJECT_ID

JSON 요청 본문:

{
  "data": {
    "title": "The Shawshank Redemption (updated)"
  },
  "vectors": {
    "plot_embedding": {
      "dense": {
        "values": [
          1.0,
          1.0,
          1.0
        ]
      }
    }
  }
}

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

다음과 비슷한 JSON 응답이 표시됩니다.

{
  "name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/DATA_OBJECT_ID",
  "data": {
    "title": "The Shawshank Redemption (updated)"
  },
  "vectors": {
    "plot_embedding": {
      "dense": {
        "values": [
          1,
          1,
          1
        ]
      }
    }
  }
}

gcloud

아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.

  • DATA_OBJECT_ID: 데이터 객체의 ID입니다.
  • COLLECTION_ID: 컬렉션의 ID입니다.
  • LOCATION: Agent Platform을 사용하는 리전입니다.
  • PROJECT_ID: Google Cloud 프로젝트 ID

다음 명령어를 실행합니다.

Linux, macOS 또는 Cloud Shell

gcloud vector-search collections data-objects update DATA_OBJECT_ID \
  --collection=COLLECTION_ID \
  --location=LOCATION \
  --project=PROJECT_ID \
  --data='{"title": "The Shawshank Redemption (updated)"}' \
  --update-vectors='{"plot_embedding": {"dense": {"values": [1.0, 1.0, 1.0]}}}'

Windows(PowerShell)

gcloud vector-search collections data-objects update DATA_OBJECT_ID `
  --collection=COLLECTION_ID `
  --location=LOCATION `
  --project=PROJECT_ID `
  --data='{"title": "The Shawshank Redemption (updated)"}' `
  --update-vectors='{"plot_embedding": {"dense": {"values": [1.0, 1.0, 1.0]}}}'

Windows(cmd.exe)

gcloud vector-search collections data-objects update DATA_OBJECT_ID ^
  --collection=COLLECTION_ID ^
  --location=LOCATION ^
  --project=PROJECT_ID ^
  --data='{"title": "The Shawshank Redemption (updated)"}' ^
  --update-vectors='{"plot_embedding": {"dense": {"values": [1.0, 1.0, 1.0]}}}'

다음과 비슷한 응답이 표시됩니다.

Updated dataObject [DATA_OBJECT_ID].

Python

from google.cloud import vectorsearch_v1

# Create the client
data_object_service_client = vectorsearch_v1.DataObjectServiceClient()

# Initialize request
data_object = vectorsearch_v1.DataObject(
    name="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/DATA_OBJECT_ID",
    data={"title": "The Shawshank Redemption (updated)"},
    vectors={
        "plot_embedding": {
            "dense": {"values": [1., 1., 1.]}
        },
    },
)
request = vectorsearch_v1.UpdateDataObjectRequest(
    data_object=data_object,
)

# Make the request
response = data_object_service_client.update_data_object(request=request)

# Handle the response
print(response)

데이터 객체 일괄 업데이트

한 번에 여러 데이터 객체를 업데이트하려면 batchUpdate를 사용하세요. 단일 배치에서 최대 1,000개의 데이터 객체를 업데이트할 수 있습니다. 각 레코드별 요청은 dataObject (전체 리소스 name와 변경하려는 필드를 포함해야 함)와 덮어쓸 필드를 나열하는 updateMask를 지정합니다. 마스크에 나열되지 않은 필드는 변경되지 않습니다.

REST

요청 데이터를 사용하기 전에 다음을 바꿉니다.

  • COLLECTION_ID: 컬렉션의 ID입니다.
  • LOCATION: Agent Platform을 사용하는 리전입니다.
  • PROJECT_ID: Google Cloud 프로젝트 ID

HTTP 메서드 및 URL: 

POST https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:batchUpdate

JSON 요청 본문:

{
  "requests": [
    {
      "dataObject": {
        "name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-1",
        "data": { "genre": "Thriller" }
      },
      "updateMask": "data.genre"
    },
    {
      "dataObject": {
        "name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-2",
        "vectors": {
          "plot_embedding": {
            "dense": { "values": [0.21, 0.34, 0.55] }
          }
        }
      },
      "updateMask": "vectors.plot_embedding"
    }
  ]
}

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

다음과 비슷한 JSON 응답이 표시됩니다.

{}

gcloud

아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.

  • COLLECTION_ID: 컬렉션의 ID입니다.
  • LOCATION: Agent Platform을 사용하는 리전입니다.
  • PROJECT_ID: Google Cloud 프로젝트 ID

다음 명령어를 실행합니다.

Linux, macOS 또는 Cloud Shell

gcloud vector-search collections data-objects batch-update \
  --collection=COLLECTION_ID \
  --location=LOCATION \
  --project=PROJECT_ID \
  --requests='[
    {
      "dataObject":{"name":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-1","data":{"genre":"Thriller"}},
      "updateMask":"data.genre"
    },
    {
      "dataObject":{"name":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-2","vectors":{"plot_embedding":{"dense":{"values":[0.21,0.34,0.55]}}}},
      "updateMask":"vectors.plot_embedding"
    }
  ]'

Windows(PowerShell)

gcloud vector-search collections data-objects batch-update `
  --collection=COLLECTION_ID `
  --location=LOCATION `
  --project=PROJECT_ID `
  --requests='[
    {
      "dataObject":{"name":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-1","data":{"genre":"Thriller"}},
      "updateMask":"data.genre"
    },
    {
      "dataObject":{"name":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-2","vectors":{"plot_embedding":{"dense":{"values":[0.21,0.34,0.55]}}}},
      "updateMask":"vectors.plot_embedding"
    }
  ]'

Windows(cmd.exe)

gcloud vector-search collections data-objects batch-update ^
  --collection=COLLECTION_ID ^
  --location=LOCATION ^
  --project=PROJECT_ID ^
  --requests='[
    {
      "dataObject":{"name":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-1","data":{"genre":"Thriller"}},
      "updateMask":"data.genre"
    },
    {
      "dataObject":{"name":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-2","vectors":{"plot_embedding":{"dense":{"values":[0.21,0.34,0.55]}}}},
      "updateMask":"vectors.plot_embedding"
    }
  ]'

Python

from google.cloud import vectorsearch_v1
from google.protobuf import field_mask_pb2

# Create the client
data_object_service_client = vectorsearch_v1.DataObjectServiceClient()

parent = "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID"

# Each entry specifies the DataObject to update (with its full resource
# name) and an update_mask listing the fields to overwrite. Fields not
# listed in the mask are left unchanged.
requests = [
    vectorsearch_v1.UpdateDataObjectRequest(
        data_object=vectorsearch_v1.DataObject(
            name=f"{parent}/dataObjects/movie-1",
            data={"genre": "Thriller"},
        ),
        update_mask=field_mask_pb2.FieldMask(paths=["data.genre"]),
    ),
    vectorsearch_v1.UpdateDataObjectRequest(
        data_object=vectorsearch_v1.DataObject(
            name=f"{parent}/dataObjects/movie-2",
            vectors={
                "plot_embedding": {"dense": {"values": [0.21, 0.34, 0.55]}},
            },
        ),
        update_mask=field_mask_pb2.FieldMask(paths=["vectors.plot_embedding"]),
    ),
]

request = vectorsearch_v1.BatchUpdateDataObjectsRequest(
    parent=parent,
    requests=requests,
)

# Make the request
data_object_service_client.batch_update_data_objects(request=request)

데이터 객체 가져오기

다음 예에서는 Cloud Storage의 데이터 객체를 ID가 COLLECTION_ID인 컬렉션으로 가져오는 방법을 보여줍니다. 대규모 데이터 세트에는 가져오기를 사용하고, 소규모 일괄 수집 (최대 1,000개 레코드)의 경우 데이터 객체를 일괄적으로 생성하는 것이 좋습니다.

REST

요청 데이터를 사용하기 전에 다음을 바꿉니다.

  • COLLECTION_ID: 컬렉션의 ID입니다.
  • LOCATION: Agent Platform을 사용하는 리전입니다.
  • PROJECT_ID: Google Cloud 프로젝트 ID

HTTP 메서드 및 URL: 

POST https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID:importDataObjects

JSON 요청 본문:

{
  "gcsImport": {
    "contentsUri": "gs://your-bucket/path/to/your-data.json",
    "errorUri": "gs://your-bucket/path/to/import-errors/",
    "outputUri": "gs://your-bucket/path/to/import-output/"
  }
}

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

다음과 비슷한 JSON 응답이 표시됩니다.

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/operation-1770039043815-649d75471f76e-08de3049-276a02be",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.vectorsearch.v1.ImportDataObjectsMetadata",
    "createTime": "2026-02-02T13:30:43.874527852Z"
  },
  "done": false
}

gcloud

아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.

  • COLLECTION_ID: 컬렉션의 ID입니다.
  • LOCATION: Agent Platform을 사용하는 리전입니다.
  • PROJECT_ID: Google Cloud 프로젝트 ID

다음 명령어를 실행합니다.

Linux, macOS 또는 Cloud Shell

gcloud vector-search collections import-data-objects COLLECTION_ID \
  --location=LOCATION \
  --project=PROJECT_ID \
  --gcs-import-contents-uri="gs://your-bucket/path/to/your-data.json" \
  --gcs-import-error-uri="gs://your-bucket/path/to/import-errors/" \
  --gcs-import-output-uri="gs://your-bucket/path/to/import-output/" \
  --async

Windows(PowerShell)

gcloud vector-search collections import-data-objects COLLECTION_ID `
  --location=LOCATION `
  --project=PROJECT_ID `
  --gcs-import-contents-uri="gs://your-bucket/path/to/your-data.json" `
  --gcs-import-error-uri="gs://your-bucket/path/to/import-errors/" `
  --gcs-import-output-uri="gs://your-bucket/path/to/import-output/" `
  --async

Windows(cmd.exe)

gcloud vector-search collections import-data-objects COLLECTION_ID ^
  --location=LOCATION ^
  --project=PROJECT_ID ^
  --gcs-import-contents-uri="gs://your-bucket/path/to/your-data.json" ^
  --gcs-import-error-uri="gs://your-bucket/path/to/import-errors/" ^
  --gcs-import-output-uri="gs://your-bucket/path/to/import-output/" ^
  --async

Python

from google.cloud import vectorsearch_v1

# Create the client
vector_search_service_client = vectorsearch_v1.VectorSearchServiceClient()

# Initialize request
request = vectorsearch_v1.ImportDataObjectsRequest(
    name="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
    gcs_import={
      "contents_uri": "gs://your-bucket/path/to/your-data/",
      "error_uri": "gs://your-bucket/path/to/import-errors/",
    },
)

# Make the request
operation = vector_search_service_client.import_data_objects(request=request)

# Wait for the result (note this may take up to several minutes)
operation.result()

폴더 gs://your-bucket/path/to/your-data/에는 각각 여러 데이터 객체를 포함하는 하나 이상의 파일이 포함될 수 있습니다. 여러 파일에 분산된 대규모 데이터 세트에 이 구조를 사용합니다. 에이전트 검색에서 지원되는 파일 형식은 다음과 같습니다.

  • 각 줄이 id, data, vectors의 세 가지 최상위 속성이 있는 JSON 객체인 JSONL 직접 검사하고 수정할 수 있는 사람이 읽을 수 있는 입력을 원하는 경우 새 에이전트 검색 데이터 세트에 이 형식을 사용합니다.
  • AVRO: 콤팩트하고 스키마가 검증된 바이너리 형식이 필요한 경우(일반적으로 Dataflow, Beam, Spark와 같은 데이터 파이프라인 도구에서 생성된 대규모 데이터 세트의 경우) 새 에이전트 검색 데이터 세트에 이 형식을 사용합니다.
  • 벡터 검색 JSON: 기존 벡터 검색 (벡터 검색 1.0) JSON 데이터 세트를 이전하고 이를 그대로 재사용하려는 경우에만 이 형식을 사용합니다.
  • 벡터 검색 AVRO: 기존 벡터 검색 (벡터 검색 1.0) AVRO 데이터 세트를 이전하고 이를 그대로 재사용하려는 경우에만 이 형식을 사용합니다.

다음은 필수 속성이 포함된 JSONL의 예시를 보여줍니다.

{
  "id": "movie-789",
  "data": {
    "title":"The Shawshank Redemption",
    "plot": "...",
    "year":1994,
    "avg_rating": 8.5,
    "movie_runtime_info": {
        "hours": 2,
        "minutes": 5
    },
  },
  "vectors": {
    "title_embedding": [-0.23, 0.88, 0.11, ...],
    "sparse_embedding": {
      "values": [0.01, -0.93, 0.27, ...],
      "indices": [23, 83, 131, ...]
    }
  }
}

AVRO

AVRO 파일의 경우 각 레코드는 표시된 DataObject Avro 스키마를 준수해야 합니다. 필드는 JSONL 형식을 반영합니다.

  • id (string 필요).
  • vectors (map, 기본값 {}). 각 항목은 벡터 이름으로 키가 지정되고 값은 float의 array (밀도 벡터) 또는 values (float 배열) 및 indices (long 배열)이 있는 SparseVector 레코드입니다.
  • data (map null 허용, 기본값 null). 키는 데이터 필드 이름입니다. 각 값은 value 필드가 지원되는 기본 유형 (boolean, int, long, float, double, string)과 중첩 구조의 경우 DataValue의 array 및 string~DataValue의 map의 합집합인 DataValue 레코드입니다.
  • etag (null 허용 string, 기본값 null)
{
  "namespace": "com.google.cloud.ai.vectorsearch",
  "type": "record",
  "name": "DataObject",
  "fields": [
    {
      "name": "id",
      "type": "string"
    },
    {
      "name": "vectors",
      "type": {
        "type": "map",
        "values": [
          {
            "type": "array",
            "items": "float"
          },
          {
            "type": "record",
            "name": "SparseVector",
            "fields": [
              {
                "name": "values",
                "type": { "type": "array", "items": "float" }
              },
              {
                "name": "indices",
                "type": { "type": "array", "items": "long" }
              }
            ]
          }
        ]
      },
      "default": {}
    },
    {
      "name": "data",
      "type": [
        "null",
        {
          "type": "map",
          "values": {
            "type": "record",
            "name": "DataValue",
            "fields": [
              {
                "name": "value",
                "type": [
                  "boolean",
                  "int",
                  "long",
                  "float",
                  "double",
                  "string",
                  {
                    "type": "array",
                    "items": "DataValue"
                  },
                  {
                    "type": "map",
                    "values": "DataValue"
                  }
                ]
              }
            ]
          }
        }
      ],
      "default": null
    },
    {
      "name": "etag",
      "type": [
        "null",
        "string"
      ],
      "default": null
    }
  ]
}

다음 스니펫은 앞의 JSONL 예시와 일치하는 단일 AVRO 레코드의 개념적 콘텐츠를 보여줍니다. 이 스키마에서는 data의 각 항목이 DataValue 레코드 (단일 value 필드 포함)로 래핑됩니다. 이는 AVRO가 data에서 이기종 유형을 나타내는 방식입니다.

{
  "id": "movie-789",
  "vectors": {
    "title_embedding": [-0.23, 0.88, 0.11],
    "sparse_embedding": {
      "values": [0.01, -0.93, 0.27],
      "indices": [23, 83, 131]
    }
  },
  "data": {
    "title": { "value": "The Shawshank Redemption" },
    "plot": { "value": "..." },
    "year": { "value": 1994 },
    "avg_rating": { "value": 8.5 },
    "movie_runtime_info": {
      "value": {
        "hours":   { "value": 2 },
        "minutes": { "value": 5 }
      }
    }
  }
}

데이터 객체 내보내기

다음 예에서는 컬렉션의 모든 데이터 객체를 JSONL 형식으로 Cloud Storage에 내보내는 방법을 보여줍니다. 대상 버킷은 컬렉션과 동일한 리전에 있어야 합니다. 내보내기는 장기 실행 작업입니다.

REST

요청 데이터를 사용하기 전에 다음을 바꿉니다.

  • COLLECTION_ID: 컬렉션의 ID입니다.
  • LOCATION: Agent Platform을 사용하는 리전입니다.
  • PROJECT_ID: Google Cloud 프로젝트 ID

HTTP 메서드 및 URL: 

POST https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID:exportDataObjects

JSON 요청 본문:

{
  "gcsDestination": {
    "exportUri": "gs://your-bucket/path/to/export-dir/",
    "format": "JSONL"
  }
}

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

다음과 비슷한 JSON 응답이 표시됩니다.

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/operation-1770039043815-649d75471f76e-08de3049-276a02be",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.vectorsearch.v1.ExportDataObjectsMetadata",
    "createTime": "2026-02-02T13:30:43.874527852Z"
  },
  "done": false
}

gcloud

아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.

  • COLLECTION_ID: 컬렉션의 ID입니다.
  • LOCATION: Agent Platform을 사용하는 리전입니다.
  • PROJECT_ID: Google Cloud 프로젝트 ID

다음 명령어를 실행합니다.

Linux, macOS 또는 Cloud Shell

gcloud vector-search collections export-data-objects COLLECTION_ID \
  --location=LOCATION \
  --project=PROJECT_ID \
  --gcs-destination-export-uri="gs://your-bucket/path/to/export-dir/" \
  --gcs-destination-format="jsonl" \
  --async

Windows(PowerShell)

gcloud vector-search collections export-data-objects COLLECTION_ID `
  --location=LOCATION `
  --project=PROJECT_ID `
  --gcs-destination-export-uri="gs://your-bucket/path/to/export-dir/" `
  --gcs-destination-format="jsonl" `
  --async

Windows(cmd.exe)

gcloud vector-search collections export-data-objects COLLECTION_ID ^
  --location=LOCATION ^
  --project=PROJECT_ID ^
  --gcs-destination-export-uri="gs://your-bucket/path/to/export-dir/" ^
  --gcs-destination-format="jsonl" ^
  --async

Python

from google.cloud import vectorsearch_v1

# Create the client
vector_search_service_client = vectorsearch_v1.VectorSearchServiceClient()

# Initialize request
request = vectorsearch_v1.ExportDataObjectsRequest(
    name="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
    gcs_destination={
        "export_uri": "gs://your-bucket/path/to/export-dir/",
        "format": vectorsearch_v1.ExportDataObjectsRequest.GcsExportDestination.Format.JSONL,
    },
)

# Make the request
operation = vector_search_service_client.export_data_objects(request=request)

# Wait for the result (note this may take up to several minutes)
operation.result()

데이터 객체 삭제

다음 예시에서는 ID가 COLLECTION_ID인 컬렉션에서 단일 데이터 객체 DATA_OBJECT_ID을 삭제하는 방법을 보여줍니다.

REST

요청 데이터를 사용하기 전에 다음을 바꿉니다.

  • DATA_OBJECT_ID: 데이터 객체의 ID입니다.
  • COLLECTION_ID: 컬렉션의 ID입니다.
  • LOCATION: Agent Platform을 사용하는 리전입니다.
  • PROJECT_ID: Google Cloud 프로젝트 ID

HTTP 메서드 및 URL: 

DELETE https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/DATA_OBJECT_ID

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

다음과 비슷한 JSON 응답이 표시됩니다.

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/operation-1770039043815-649d75471f76e-08de3049-276a02be",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.vectorsearch.v1.ExportDataObjectsMetadata",
    "createTime": "2026-02-02T13:30:43.874527852Z"
  },
  "done": false
}

gcloud

아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.

  • DATA_OBJECT_ID: 데이터 객체의 ID입니다.
  • COLLECTION_ID: 컬렉션의 ID입니다.
  • LOCATION: Agent Platform을 사용하는 리전입니다.
  • PROJECT_ID: Google Cloud 프로젝트 ID

다음 명령어를 실행합니다.

Linux, macOS 또는 Cloud Shell

gcloud vector-search collections data-objects delete DATA_OBJECT_ID \
  --collection=COLLECTION_ID \
  --location=LOCATION \
  --project=PROJECT_ID

Windows(PowerShell)

gcloud vector-search collections data-objects delete DATA_OBJECT_ID `
  --collection=COLLECTION_ID `
  --location=LOCATION `
  --project=PROJECT_ID

Windows(cmd.exe)

gcloud vector-search collections data-objects delete DATA_OBJECT_ID ^
  --collection=COLLECTION_ID ^
  --location=LOCATION ^
  --project=PROJECT_ID

다음과 비슷한 응답이 표시됩니다.

Deleted dataObject [DATA_OBJECT_ID].

Python

from google.cloud import vectorsearch_v1

# Create the client
data_object_service_client = vectorsearch_v1.DataObjectServiceClient()

# Initialize request
request = vectorsearch_v1.DeleteDataObjectRequest(
    name="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/DATA_OBJECT_ID",
)

# Make the request
data_object_service_client.delete_data_object(request=request)

데이터 객체 일괄 삭제

한 번에 여러 데이터 객체를 삭제하려면 정규화된 데이터 객체 리소스 이름 목록과 함께 batchDelete를 사용하세요. 한 번에 최대 1,000개의 데이터 객체를 삭제할 수 있습니다.

REST

요청 데이터를 사용하기 전에 다음을 바꿉니다.

  • COLLECTION_ID: 컬렉션의 ID입니다.
  • LOCATION: Agent Platform을 사용하는 리전입니다.
  • PROJECT_ID: Google Cloud 프로젝트 ID

HTTP 메서드 및 URL: 

POST https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:batchDelete

JSON 요청 본문:

{
  "requests": [
    { "name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-1" },
    { "name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-2" }
  ]
}

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

다음과 비슷한 JSON 응답이 표시됩니다.

{}

gcloud

아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.

  • COLLECTION_ID: 컬렉션의 ID입니다.
  • LOCATION: Agent Platform을 사용하는 리전입니다.
  • PROJECT_ID: Google Cloud 프로젝트 ID

다음 명령어를 실행합니다.

Linux, macOS 또는 Cloud Shell

gcloud vector-search collections data-objects batch-delete \
  --collection=COLLECTION_ID \
  --location=LOCATION \
  --project=PROJECT_ID \
  --requests='[
    {"name":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-1"},
    {"name":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-2"}
  ]'

Windows(PowerShell)

gcloud vector-search collections data-objects batch-delete `
  --collection=COLLECTION_ID `
  --location=LOCATION `
  --project=PROJECT_ID `
  --requests='[
    {"name":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-1"},
    {"name":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-2"}
  ]'

Windows(cmd.exe)

gcloud vector-search collections data-objects batch-delete ^
  --collection=COLLECTION_ID ^
  --location=LOCATION ^
  --project=PROJECT_ID ^
  --requests='[
    {"name":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-1"},
    {"name":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-2"}
  ]'

Python

from google.cloud import vectorsearch_v1

# Create the client
data_object_service_client = vectorsearch_v1.DataObjectServiceClient()

parent = "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID"

requests = [
    vectorsearch_v1.DeleteDataObjectRequest(
        name=f"{parent}/dataObjects/movie-1",
    ),
    vectorsearch_v1.DeleteDataObjectRequest(
        name=f"{parent}/dataObjects/movie-2",
    ),
]

request = vectorsearch_v1.BatchDeleteDataObjectsRequest(
    parent=parent,
    requests=requests,
)

# Make the request
data_object_service_client.batch_delete_data_objects(request=request)

데이터 객체 수

컬렉션에 포함된 데이터 객체의 수를 세려면 COUNT 집계 메서드와 함께 aggregate 작업을 사용합니다. 동일한 호출은 선택적 JSON 필터 표현식을 허용하므로 술어 (예: genre == "sci-fi")와 일치하는 데이터 객체만 셀 수 있습니다.

컬렉션의 모든 데이터 객체를 계산하려면 필터를 생략합니다.

REST

요청 데이터를 사용하기 전에 다음을 바꿉니다.

  • COLLECTION_ID: 컬렉션의 ID입니다.
  • LOCATION: Agent Platform을 사용하는 리전입니다.
  • PROJECT_ID: Google Cloud 프로젝트 ID

HTTP 메서드 및 URL: 

POST https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:aggregate

JSON 요청 본문:

{
  "aggregate": "COUNT",
  "filter": { "genre": { "$eq": "sci-fi" } }
}

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

다음과 비슷한 JSON 응답이 표시됩니다.

{
  "aggregateResults": [
    { "count": "42" }
  ]
}

gcloud

아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.

  • COLLECTION_ID: 컬렉션의 ID입니다.
  • LOCATION: Agent Platform을 사용하는 리전입니다.
  • PROJECT_ID: Google Cloud 프로젝트 ID

다음 명령어를 실행합니다.

Linux, macOS 또는 Cloud Shell

gcloud vector-search collections data-objects aggregate \
  --collection=COLLECTION_ID \
  --location=LOCATION \
  --project=PROJECT_ID \
  --aggregation-method=count \
  --json-filter='{"genre": {"$eq": "sci-fi"}}'

Windows(PowerShell)

gcloud vector-search collections data-objects aggregate `
  --collection=COLLECTION_ID `
  --location=LOCATION `
  --project=PROJECT_ID `
  --aggregation-method=count `
  --json-filter='{"genre": {"$eq": "sci-fi"}}'

Windows(cmd.exe)

gcloud vector-search collections data-objects aggregate ^
  --collection=COLLECTION_ID ^
  --location=LOCATION ^
  --project=PROJECT_ID ^
  --aggregation-method=count ^
  --json-filter='{"genre": {"$eq": "sci-fi"}}'

Python

from google.cloud import vectorsearch_v1
from google.protobuf import struct_pb2
from google.protobuf import json_format

# Create the client
search_client = vectorsearch_v1.DataObjectSearchServiceClient()

parent = "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID"

# Optional: build a JSON filter. Omit `filter=` to count everything.
filter_struct = json_format.ParseDict(
    {"genre": {"$eq": "sci-fi"}}, struct_pb2.Struct()
)

request = vectorsearch_v1.AggregateDataObjectsRequest(
    parent=parent,
    aggregate=vectorsearch_v1.AggregationMethod.COUNT,
    filter=filter_struct,
)

# Make the request
response = search_client.aggregate_data_objects(request=request)

# The count value is returned in aggregate_results[0].
for result in response.aggregate_results:
    print(result)

다음 단계