BigQuery에서 색인 데이터 가져오기

이 가이드에서는 ImportIndex API를 사용하여 BigQuery에서 벡터 검색으로 색인 데이터를 가져오는 방법을 설명합니다. 이를 통해 벡터 삽입이 포함된 BigQuery 테이블에서 벡터 검색 색인을 직접 채우는 프로세스를 간소화할 수 있습니다.

가져오기를 위해 BigQuery 데이터 준비

색인 데이터를 가져오기 전에 BigQuery 테이블에 다음 열이 있어야 합니다.

  • 고유 식별자: 이 열에는 각 데이터 포인트의 고유 식별자가 포함됩니다. 벡터 검색의 id 필드에 매핑됩니다.

  • 벡터 임베딩: 이 열에는 반복되는 FLOAT 필드로 표현된 벡터 임베딩이 포함됩니다. 벡터 검색의 임베딩 필드에 매핑됩니다.

선택적으로 다음 열을 포함할 수 있습니다.

  • 제한: 문자열 및 숫자 제한을 위한 열로, 검색 중에 데이터를 필터링할 수 있습니다.

  • 메타데이터: 벡터 검색 색인 쿼리 결과와 함께 반환될 메타데이터 열입니다.

가져오기를 위해 벡터 검색 색인 준비

BigQuery 데이터를 준비한 후 대상 벡터 검색 색인이 다음을 충족하는지 확인합니다.

  • 프로젝트 내 벡터 검색에 있음: 이 색인은 가져온 데이터의 대상으로 사용됩니다. 색인은 프로젝트 내에서 만들어야 합니다.

  • 데이터를 덮어쓰거나 추가하도록 설정됨: 가져오기 프로세스 중에 벡터 검색 색인 내 기존 데이터를 덮어쓰거나 BigQuery에서 가져온 데이터를 추가할 수 있습니다. 덮어쓰기는 현재 데이터 포인트를 가져온 데이터로 대체합니다. 추가하면 새 데이터가 기존 색인에 추가됩니다.

  • 차원 일치: BigQuery 데이터에 저장된 임베딩의 차원은 벡터 검색 색인에 구성된 차원과 동일해야 합니다.

ImportIndexRequest 지정

BigQuery에서 데이터를 가져오기 전에 대상 색인, 기존 데이터 덮어쓰기 여부, BigQuery 연결 구성을 지정하는 ImportIndexRequest 객체를 만듭니다. 이 요청 객체를 ImportIndex API로 보냅니다.

다음은 JSON 형식의 ImportIndexRequest의 예입니다.

{
  "name": "projects/[PROJECT_ID]/locations/[LOCATION]/indexes/[INDEX_ID]",
  "isCompleteOverwrite": true,
  "config": {
    "bigQuerySourceConfig": {
      "tablePath": "[PROJECT_ID].[DATASET_ID].[TABLE_ID]",
      "datapointFieldMapping": {
        "idColumn": "[ID_COLUMN_NAME]",
        "embeddingColumn": "[EMBEDDING_COLUMN_NAME]",
        "restricts": [
          {
            "namespace": "[RESTRICT_NAMESPACE]",
            "allowColumn": ["[RESTRICT_ALLOW_COLUMN_NAME]"],
            "denyColumn": ["[RESTRICT_DENY_COLUMN_NAME]"]
          }
        ],
        "numericRestricts": [
          {
            "namespace": "[RESTRICT_NAMESPACE]",
            "valueColumn": "[RESTRICT_VALUE_COLUMN_NAME]",
            "valueType": "INT"
          }
        ],
        "metadataColumns": ["METADATA_COLUMN1", "METADATA_COLUMN2", ...]
      }
    }
  }
}

  • name: 데이터를 가져올 벡터 검색 색인의 전체 리소스 이름입니다.

  • isCompleteOverwrite: 색인의 기존 데이터를 덮어쓸지 여부를 나타내는 불리언입니다. 기존 데이터를 대체하려면 true로 설정합니다.

  • config: BigQuery 소스의 구성을 포함합니다.

    • bigquerySourceConfig: BigQuery 테이블에 연결하기 위한 세부정보를 지정합니다.

    • tablePath: [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.7
      feature_vector: 0.8
      restricts {
        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
  }
}