이 가이드에서는 ImportIndex API를 사용하여 BigQuery에서 벡터 검색으로 색인 데이터를 가져오는 방법을 설명합니다. 이를 통해 벡터 삽입이 포함된 BigQuery 테이블에서 벡터 검색 색인을 직접 채우는 프로세스를 간소화할 수 있습니다.
가져오기를 위해 BigQuery 데이터 준비
색인 데이터를 가져오기 전에 BigQuery 테이블에 다음 열이 있어야 합니다.
고유 식별자: 이 열에는 각 데이터 포인트의 고유 식별자가 포함됩니다. 벡터 검색의 id 필드에 매핑됩니다.
벡터 임베딩: 이 열에는 반복되는 FLOAT 필드로 표현된 벡터 임베딩이 포함됩니다. 벡터 검색의 임베딩 필드에 매핑됩니다.
선택적으로 다음 열을 포함할 수 있습니다.
제한: 문자열 및 숫자 제한을 위한 열로, 검색 중에 데이터를 필터링할 수 있습니다.
메타데이터: 벡터 검색 색인 쿼리 결과와 함께 반환될 메타데이터 열입니다.
가져오기를 위해 벡터 검색 색인 준비
BigQuery 데이터를 준비한 후 대상 벡터 검색 색인이 다음을 충족하는지 확인합니다.
프로젝트 내 벡터 검색에 있음: 이 색인은 가져온 데이터의 대상으로 사용됩니다. 색인은 프로젝트 내에서 만들어야 합니다.
데이터를 덮어쓰거나 추가하도록 설정됨: 가져오기 프로세스 중에 벡터 검색 색스 내 기존 데이터를 덮어쓰거나 BigQuery에서 가져온 데이터를 추가할 수 있습니다. 덮어쓰기는 현재 데이터 포인트를 가져온 데이터로 대체합니다. 추가하면 새 데이터가 기존 색인에 추가됩니다.
차원 일치: BigQuery 데이터에 저장된 임베딩의 차원은 벡터 검색 색인에 구성된 차원과 동일해야 합니다.
ImportIndexRequest 지정
BigQuery에서 데이터를 가져오기 전에 대상 색인, 기존 데이터 덮어쓰기 여부, BigQuery 연결 구성을 지정하는 ImportIndexRequest 객체를 만듭니다. 이 요청 객체를 ImportIndex API로 보냅니다.
isCompleteOverwrite: 색인의 기존 데이터를 덮어쓸지 여부를 나타내는 불리언입니다. 기존 데이터를 대체하려면 true로 설정합니다.
config: BigQuery 소스의 구성을 포함합니다.
bigquerySourceConfig: BigQuery 테이블에 연결하기 위한 세부정보를 지정합니다.
tablePath: bq://[PROJECT_ID].[DATASET_ID].[TABLE_ID] 형식의 BigQuery 테이블 전체 경로입니다.
datapointFieldMapping: BigQuery 테이블의 열을 벡터 검색의 필드에 매핑합니다.
idColumn: 고유 식별자가 포함된 열의 이름입니다.
embeddingColumn: 벡터 임베딩이 포함된 열의 이름입니다.
restricts: (선택사항) 문자열 제한을 지정합니다.
namespace: 제한의 네임스페이스입니다.
allowColumn: 제한의 허용된 값에 대한 열 이름이 포함된 배열입니다.
denyColumn: 제한에 대해 거부된 값의 열 이름이 포함된 배열입니다.
numericRestricts: (선택사항) 숫자 제한을 지정합니다.
namespace: 숫자 제한의 네임스페이스입니다.
value_column: 숫자 값이 포함된 열의 이름입니다.
value_type: 숫자 값의 유형입니다(예: INT, FLOAT, DOUBLE).
metadataColumns: (선택사항) 기능 임베딩에 포함할 메타데이터 필드입니다. 이러한 메타데이터 필드는 색인 검색 결과에서 가져올 수 있지만 검색 자체에는 영향을 미치지 않습니다. 예를 들어 메타데이터 필드에서는 필터링을 실행할 수 없습니다.
가져오기 실행
ImportIndexRequest를 만든 후 ImportIndex API 엔드포인트로 전송합니다. 이렇게 하면 가져오기 프로세스가 트리거되어 BigQuery에서 데이터를 내보내고 벡터 검색 색인으로 데이터를 수집합니다. ImportIndex는 장기 실행 작업을 반환합니다. 작업 ID를 사용하여 가져오기 작업의 진행 상황을 모니터링할 수 있습니다.
가져온 데이터가 저장되면 벡터 검색 색인 내에 상주하며 다른 방법을 사용하여 수집된 데이터와 구별할 수 없습니다. 표준 벡터 검색 API를 사용하여 색인을 계속 관리할 수 있습니다.
다음 코드 샘플은 return_full_datapoint이 true로 설정된 쿼리 결과와 genre을 지정하는 BigQuery 커넥터 구성이 year 숫자 제한 및 메타데이터 열 title 및 description을 제한하는 것을 보여줍니다.
nearest_neighbors{neighbors{datapoint{datapoint_id:"4"feature_vector:0.7feature_vector:0.8restricts{namespace:"genre"allow_list:"Drama"}embedding_metadata{title:"A Movie"description:"The story of A Movie..."}crowding_tag{crowding_attribute:"0"}numeric_restricts{namespace:"year"value_int:1942}}distance:0.75}}
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-04(UTC)"],[],[],null,["# Import index data from BigQuery\n\n| **Preview**\n|\n|\n| This feature is subject to the \"Pre-GA Offerings Terms\" in the General Service Terms section\n| of the [Service Specific Terms](/terms/service-terms#1).\n|\n| Pre-GA features are available \"as is\" and might have limited support.\n|\n| For more information, see the\n| [launch stage descriptions](/products#product-launch-stages).\n\nThis guide explains how to import index data from BigQuery into\nVector Search with the `ImportIndex` API, streamlining\nthe process of populating Vector Search indexes directly from\nyour BigQuery tables that contain vector embeddings.\n\nPreparing BigQuery data for import\n----------------------------------\n\nBefore importing index data, your BigQuery table must have the\nfollowing columns:\n\n- **Unique identifiers** : This column contains unique identifiers for each\n data point. It is mapped to the `id` field in Vector Search.\n\n- **Vector embeddings** : This column contains the vector embeddings,\n represented as a repeated `FLOAT` field. It is mapped to the embedding\n field in Vector Search.\n\nOptionally, you can include the following columns:\n\n- **Restricts**: These are columns for string and numeric restricts, which\n lets you filter your data during searches.\n\n- **Metadata**: These are columns of metadata to be returned with\n Vector Search index query results.\n\nPreparing Vector Search index for import\n----------------------------------------\n\nOnce you've prepared your BigQuery data, ensure the destination\nVector Search index:\n\n- **Exists in Vector Search within your project**: This index\n serves as the destination for your imported data. The index must be created\n within your project.\n\n- **Is set to overwrite or append data**: During the import process, you\n have the option to either overwrite the existing data within your\n Vector Search index or append the data imported from\n BigQuery. Overwriting replaces the current data points\n with the imported data. Appending adds the new data to the existing\n index.\n\n- **Matches dimensionality**: The dimensionality of the embeddings stored in\n your BigQuery data must be identical to the dimensionality\n configured for your Vector Search index.\n\nSpecifying the `ImportIndexRequest`\n-----------------------------------\n\nBefore importing data from BigQuery, create an\n`ImportIndexRequest` object that specifies the target index, whether to\noverwrite existing data, and the configuration for connecting to\nBigQuery. Send this request object to the `ImportIndex`\nAPI.\n\nThe following is an example of an `ImportIndexRequest` in JSON format: \n\n {\n \"name\": \"projects/[PROJECT_ID]/locations/[LOCATION]/indexes/[INDEX_ID]\",\n \"isCompleteOverwrite\": true,\n \"config\": {\n \"bigQuerySourceConfig\": {\n \"tablePath\": \"[PROJECT_ID].[DATASET_ID].[TABLE_ID]\",\n \"datapointFieldMapping\": {\n \"idColumn\": \"[ID_COLUMN_NAME]\",\n \"embeddingColumn\": \"[EMBEDDING_COLUMN_NAME]\",\n \"restricts\": [\n {\n \"namespace\": \"[RESTRICT_NAMESPACE]\",\n \"allowColumn\": [\"[RESTRICT_ALLOW_COLUMN_NAME]\"],\n \"denyColumn\": [\"[RESTRICT_DENY_COLUMN_NAME]\"]\n }\n ],\n \"numericRestricts\": [\n {\n \"namespace\": \"[RESTRICT_NAMESPACE]\",\n \"valueColumn\": \"[RESTRICT_VALUE_COLUMN_NAME]\",\n \"valueType\": \"INT\"\n }\n ],\n \"metadataColumns\": [\"METADATA_COLUMN1\", \"METADATA_COLUMN2\", ...]\n }\n }\n }\n }\n\n- **`name`**: The full resource name of the Vector Search index\n where you want to import the data.\n\n- **`isCompleteOverwrite`** : A boolean that indicates whether to overwrite existing\n data in the index. Set to `true` to replace existing data.\n\n- **`config`**: Contains the configuration for the BigQuery source.\n\n - **`bigquerySourceConfig`**: Specifies the details for connecting to your\n BigQuery table.\n\n - **`tablePath`** : The full path to your BigQuery table in the\n format `[PROJECT_ID].[DATASET_ID].[TABLE_ID]`.\n\n - **`datapointFieldMapping`**: Maps the columns in your\n BigQuery table to the fields in Vector Search.\n\n - **`idColumn`**: The name of the column containing unique identifiers.\n\n - **`embeddingColumn`**: The name of the column containing vector\n embeddings.\n\n - **`restricts`**: (Optional) Specifies string restricts.\n\n - **`namespace`**: The namespace for the restrict.\n\n - **`allowColumn`**: The array containing column name(s) for allowed\n values for the restrict.\n\n - **`denyColumn`**: The array containing column name(s) for denied values\n for the restrict.\n\n - **`numericRestricts`**: (Optional) Specifies numeric restricts.\n\n - **`namespace`**: The namespace for the numeric restrict.\n\n - **`value_column`**: The name of the column containing numeric values.\n\n - **`value_type`** : The type of the numeric value such as `INT`,\n `FLOAT`, or `DOUBLE`.\n\n - **`metadataColumns`**: (Optional) Metadata fields to include with the\n feature embedding. These metadata fields can be retrieved from the index\n search results, but they don't affect the search itself. For example,\n filtering cannot be performed on metadata fields.\n\nExecuting the import\n--------------------\n\nOnce you have created an `ImportIndexRequest`, send it to the `ImportIndex` API\nendpoint. This triggers the import process, which exports data from\nBigQuery and ingests it into your Vector Search\nindex. `ImportIndex` returns a long-running operation. You can use the operation\nID to monitor the progress of the import operation.\n\nAfter the imported data is stored, it resides within your\nVector Search index and is indistinguishable from data ingested\nusing other methods. The index can continue to be managed using standard\nVector Search APIs.\n\nThe following code sample demonstrates a query result with\n`return_full_datapoint` set to true and the BigQuery connector\nconfiguration that specifies a `genre` restricts, a `year` numeric restricts,\nand metadata columns `title` and `description`. \n\n nearest_neighbors {\n neighbors {\n datapoint {\n datapoint_id: \"4\"\n feature_vector: 0.7\n feature_vector: 0.8\n restricts {\n namespace: \"genre\"\n allow_list: \"Drama\"\n }\n embedding_metadata {\n title: \"A Movie\"\n description: \"The story of A Movie...\"\n }\n crowding_tag {\n crowding_attribute: \"0\"\n }\n numeric_restricts {\n namespace: \"year\"\n value_int: 1942\n }\n }\n distance: 0.75\n }\n }"]]
