集合

在 Vector Search 2.0 中，集合用於儲存相關的資料物件。您可查詢這些物件，判斷所含資料物件的確切狀態，做為事實來源。

集合結構定義

建立集合時，您必須提供下列 JSON 結構定義：

  • 資料結構定義，提供使用者定義的資料結構。

  • 向量結構定義，用於定義及設定資料物件的向量欄位。

這些統稱為「集合結構定義」。

建立集合

以下範例示範如何建立 ID 為 COLLECTION_ID 的集合，並指定資料結構定義和向量結構定義。

REST

使用任何要求資料之前，請先修改下列項目的值：

  • COLLECTION_ID：集合 ID。
  • LOCATION：您使用 Vertex AI 的區域。
  • PROJECT_ID：您的 Google Cloud 專案 ID。

HTTP 方法和網址：

POST https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections?collection_id=COLLECTION_ID

JSON 要求主體：

{
  "data_schema": {
    "type": "object",
    "properties": {
      "year": {
        "type": "number"
      },
      "genre": {
        "type": "string"
      },
      "director": {
        "type": "string"
      },
      "title": {
        "type": "string"
      }
    }
  },
  "vector_schema": {
    "plot_embedding": {
      "dense_vector": {
        "dimensions": 3
      }
    },
    "soundtrack_embedding": {
      "dense_vector": {
        "dimensions": 5
      }
    },
    "genre_embedding": {
      "dense_vector": {
        "dimensions": 4
      }
    },
    "sparse_embedding": {
      "sparse_vector": {}
    }
  },
  "labels": {
    "fookey": "barvalue"
  }
}

請展開以下其中一個選項，以傳送要求：

您應該會收到如下的 JSON 回覆：

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.vectorsearch.v1beta.OperationMetadata",
    "createTime": "2026-01-23T17:17:29.687753204Z",
    "target": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v1beta"
  },
  "done": false
}

gcloud

使用下列任何指令資料之前，請先替換以下項目：

  • DATA_SCHEMA_FILE：資料結構定義檔案的本機路徑。
  • VECTOR_SCHEMA_FILE：向量結構定義檔案的本機路徑。
  • COLLECTION_ID：集合 ID。
  • LOCATION：您使用 Vertex AI 的區域。
  • PROJECT_ID：您的 Google Cloud 專案 ID。

執行下列指令：

Linux、macOS 或 Cloud Shell

gcloud beta vector-search collections create COLLECTION_ID \
  --data-schema=DATA_SCHEMA_FILE \
  --vector-schema=VECTOR_SCHEMA_FILE \
  --labels=fookey=barvalue \
  --location=LOCATION \
  --project=PROJECT_ID

Windows (PowerShell)

gcloud beta vector-search collections create COLLECTION_ID `
  --data-schema=DATA_SCHEMA_FILE `
  --vector-schema=VECTOR_SCHEMA_FILE `
  --labels=fookey=barvalue `
  --location=LOCATION `
  --project=PROJECT_ID

Windows (cmd.exe)

gcloud beta vector-search collections create COLLECTION_ID ^
  --data-schema=DATA_SCHEMA_FILE ^
  --vector-schema=VECTOR_SCHEMA_FILE ^
  --labels=fookey=barvalue ^
  --location=LOCATION ^
  --project=PROJECT_ID

您應該會收到類似以下的回應：

Created collection [COLLECTION_ID].

Python

from google.cloud import vectorsearch_v1beta

# Create the client
vector_search_service_client = vectorsearch_v1beta.VectorSearchServiceClient()

# The JSON schema for the data
data_schema = {
    "type": "object",
    "properties": {
        "year": {"type": "number"},
        "genre": {"type": "string"},
        "director": {"type": "string"},
        "title": {"type": "string"},
    },
}

# The JSON schema for the vector
vector_schema = {
    "plot_embedding": {"dense_vector": {"dimensions": 3}},
    "soundtrack_embedding": {"dense_vector": {"dimensions": 5}},
    "genre_embedding": {"dense_vector": {"dimensions": 4}},
    "sparse_embedding": {"sparse_vector": {}},
}

collection = vectorsearch_v1beta.Collection(
    data_schema=data_schema,
    vector_schema=vector_schema,
)
request = vectorsearch_v1beta.CreateCollectionRequest(
    parent="projects/PROJECT_ID/locations/LOCATION",
    collection_id="COLLECTION_ID",
    collection=collection,
)

# Create the collection
operation = vector_search_service_client.create_collection(request=request)
operation.result()

在這個範例中，系統會提出要求，並將 collection_id 設為 COLLECTION_ID，且要求主體包含下列項目：

  1. data_schema - 指定資料物件結構。

  2. vector_schema - 設定及定義向量欄位。

結構定義中的所有欄位都必須明確定義。系統不支援 JSON 結構定義選項 additionalProperties。

取得集合

以下範例說明如何使用 ID COLLECTION_ID 取得現有集合的參照。

REST

使用任何要求資料之前，請先修改下列項目的值：

  • COLLECTION_ID：集合 ID。
  • LOCATION：您使用 Vertex AI 的區域。
  • PROJECT_ID：您的 Google Cloud 專案 ID。

HTTP 方法和網址：

GET https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID

JSON 要求主體：

{
  "data_schema": {
    "type": "object",
    "properties": {
      "year": {
        "type": "number"
      },
      "genre": {
        "type": "string"
      },
      "director": {
        "type": "string"
      },
      "title": {
        "type": "string"
      }
    }
  },
  "vector_schema": {
    "plot_embedding": {
      "dense_vector": {
        "dimensions": 3
      }
    },
    "soundtrack_embedding": {
      "dense_vector": {
        "dimensions": 5
      }
    },
    "genre_embedding": {
      "dense_vector": {
        "dimensions": 4
      }
    },
    "sparse_embedding": {
      "sparse_vector": {}
    }
  },
  "labels": {
    "fookey": "barvalue"
  }
}

請展開以下其中一個選項，以傳送要求：

您應該會收到如下的 JSON 回覆：

{
  "name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
  "createTime": "2026-01-23T17:17:29.681218929Z",
  "updateTime": "2026-01-23T17:17:30.402200642Z",
  "labels": {
    "fookey": "barvalue"
  },
  "vectorSchema": {
    "genre_embedding": {
      "denseVector": {
        "dimensions": 4
      }
    },
    "sparse_embedding": {
      "sparseVector": {}
    },
    "plot_embedding": {
      "denseVector": {
        "dimensions": 3
      }
    },
    "soundtrack_embedding": {
      "denseVector": {
        "dimensions": 5
      }
    }
  },
  "dataSchema": {
    "type": "object",
    "properties": {
      "title": {
        "type": "string"
      },
      "year": {
        "type": "number"
      },
      "genre": {
        "type": "string"
      },
      "director": {
        "type": "string"
      }
    }
  }
}

gcloud

使用下列任何指令資料之前，請先替換以下項目：

  • COLLECTION_ID：集合 ID。
  • LOCATION：您使用 Vertex AI 的區域。
  • PROJECT_ID：您的 Google Cloud 專案 ID。

執行下列指令：

Linux、macOS 或 Cloud Shell

gcloud  beta vector-search collections describe COLLECTION_ID \
--location=LOCATION \
--project=PROJECT_ID

Windows (PowerShell)

gcloud  beta vector-search collections describe COLLECTION_ID `
--location=LOCATION `
--project=PROJECT_ID

Windows (cmd.exe)

gcloud  beta vector-search collections describe COLLECTION_ID ^
--location=LOCATION ^
--project=PROJECT_ID

您應該會收到類似以下的回應：

createTime: '2026-01-23T17:17:29.681218929Z'
dataSchema:
  properties:
    director:
      type: string
    genre:
      type: string
    title:
      type: string
    year:
      type: number
  type: object
labels:
  fookey: barvalue
name: projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID
updateTime: '2026-01-23T17:17:30.402200642Z'
vectorSchema:
  genre_embedding:
    denseVector:
      dimensions: 4
  plot_embedding:
    denseVector:
      dimensions: 3
  soundtrack_embedding:
    denseVector:
      dimensions: 5
  sparse_embedding:
    sparseVector: {}

Python

from google.cloud import vectorsearch_v1beta

# Create the client
vector_search_service_client = vectorsearch_v1beta.VectorSearchServiceClient()

# Initialize request
request = vectorsearch_v1beta.GetCollectionRequest(
    name="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
)

# Make the request
response = vector_search_service_client.get_collection(request=request)

# Handle the response
print(response)

列出集合

下列範例示範如何擷取現有集合的清單。

REST

使用任何要求資料之前，請先修改下列項目的值：

  • LOCATION：您使用 Vertex AI 的區域。
  • PROJECT_ID：您的 Google Cloud 專案 ID。

HTTP 方法和網址：

GET https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections

請展開以下其中一個選項，以傳送要求：

您應該會收到如下的 JSON 回覆：

{
  "collections": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
      "createTime": "2026-01-23T17:17:29.681218929Z",
      "updateTime": "2026-01-23T17:17:30.402200642Z",
      "labels": {
        "fookey": "barvalue"
      },
      "vectorSchema": {
        "genre_embedding": {
          "denseVector": {
            "dimensions": 4
          }
        },
        "sparse_embedding": {
          "sparseVector": {}
        },
        "plot_embedding": {
          "denseVector": {
            "dimensions": 3
          }
        },
        "soundtrack_embedding": {
          "denseVector": {
            "dimensions": 5
          }
        }
      },
      "dataSchema": {
        "type": "object",
        "properties": {
          "year": {
            "type": "number"
          },
          "genre": {
            "type": "string"
          },
          "director": {
            "type": "string"
          },
          "title": {
            "type": "string"
          }
        }
      }
    }
  ]
}

gcloud

使用下列任何指令資料之前，請先替換以下項目：

  • LOCATION：您使用 Vertex AI 的區域。
  • PROJECT_ID：您的 Google Cloud 專案 ID。

執行下列指令：

Linux、macOS 或 Cloud Shell

gcloud beta vector-search collections list \
--location=LOCATION \
--project=PROJECT_ID

Windows (PowerShell)

gcloud beta vector-search collections list `
--location=LOCATION `
--project=PROJECT_ID

Windows (cmd.exe)

gcloud beta vector-search collections list ^
--location=LOCATION ^
--project=PROJECT_ID

您應該會收到類似以下的回應：

---
createTime: '2026-01-23T17:17:29.681218929Z'
dataSchema:
  properties:
    director:
      type: string
    genre:
      type: string
    title:
      type: string
    year:
      type: number
  type: object
labels:
  fookey: barvalue
name: projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID
updateTime: '2026-01-23T17:17:30.402200642Z'
vectorSchema:
  genre_embedding:
    denseVector:
      dimensions: 4
  plot_embedding:
    denseVector:
      dimensions: 3
  soundtrack_embedding:
    denseVector:
      dimensions: 5
  sparse_embedding:
    sparseVector: {}

Python

from google.cloud import vectorsearch_v1beta

# Create the client
vector_search_service_client = vectorsearch_v1beta.VectorSearchServiceClient()

# Initialize request argument
request = vectorsearch_v1beta.ListCollectionsRequest(
    parent="projects/PROJECT_ID/locations/LOCATION",
)

# Make the request
page_result = vector_search_service_client.list_collections(request=request)

# Handle the response
for response in page_result:
    print(response)

更新集合

UpdateCollection 方法可讓您修改現有的 Collection 資源。您可以透過 update_mask 控制要更新的欄位。如未提供更新遮罩，更新要求中的任何欄位都會覆寫集合中的對應欄位。

更新遮罩中指定的欄位與 Collection 資源相關。如要使用要求中提供的資源完全取代整個集合資源，請使用 * 做為更新遮罩。

您可以更新下列欄位：

  • display_name
  • description
  • labels
  • data_schema
  • vector_schema

您可以為 data_schema 和 vector_schema 進行下列更新：

  • 新增欄位。
  • 從 vector_schema 元素中移除 vertex_embedding_config 欄位。其他欄位則無法移除。

  • 在 update__mask 中指定子欄位路徑，即可更新 data_schema 和 vector_schema 中的巢狀成員。例如：

    • data_schema.properties.new_field
    • vector_schema.my_vector_field

刪除集合

以下範例說明如何使用 ID COLLECTION_ID 刪除現有集合。

REST

使用任何要求資料之前，請先修改下列項目的值：

  • COLLECTION_ID：集合 ID。
  • LOCATION：您使用 Vertex AI 的區域。
  • PROJECT_ID：您的 Google Cloud 專案 ID。

HTTP 方法和網址：

DELETE https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID

請展開以下其中一個選項，以傳送要求：

您應該會收到如下的 JSON 回覆：

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/operation-1769280311389-64926ac77ed08-661d4521-c7d3036c",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.vectorsearch.v1beta.OperationMetadata",
    "createTime": "2026-01-24T18:45:11.402619681Z",
    "target": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
    "verb": "delete",
    "requestedCancellation": false,
    "apiVersion": "v1beta"
  },
  "done": false
}

gcloud

使用下列任何指令資料之前，請先替換以下項目：

  • COLLECTION_ID：集合 ID。
  • LOCATION：您使用 Vertex AI 的區域。
  • PROJECT_ID：您的 Google Cloud 專案 ID。

執行下列指令：

Linux、macOS 或 Cloud Shell

gcloud beta vector-search collections delete COLLECTION_ID \
--location=LOCATION \
--project=PROJECT_ID

Windows (PowerShell)

gcloud beta vector-search collections delete COLLECTION_ID `
--location=LOCATION `
--project=PROJECT_ID

Windows (cmd.exe)

gcloud beta vector-search collections delete COLLECTION_ID ^
--location=LOCATION ^
--project=PROJECT_ID

您應該會收到類似以下的回應：

Deleted collection [COLLECTION_ID].

Python

from google.cloud import vectorsearch_v1beta

# Create the client
vector_search_service_client = vectorsearch_v1beta.VectorSearchServiceClient()

# Initialize request
request = vectorsearch_v1beta.DeleteCollectionRequest(
    name="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
)

# Make the request
operation = vector_search_service_client.delete_collection(request=request)
operation.result()

後續步驟