Coleções

Na pesquisa vetorial 2.0, as coleções são usadas para armazenar objetos de dados relacionados. Eles fornecem uma fonte de verdade que pode ser consultada para determinar o estado exato dos objetos de dados que contêm.

Esquema de coleta

Ao criar uma coleção, você precisa fornecer os seguintes esquemas JSON:

Um esquema de dados, que fornece a estrutura definida pelo usuário dos seus dados.
Um esquema de vetor que define e configura os campos de vetor para seus objetos de dados.

Juntos, eles são chamados de esquema de coleta.

Criar uma coleção

O exemplo a seguir demonstra como criar uma coleção com o ID COLLECTION_ID, especificando um esquema de dados e um esquema de vetor.

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

COLLECTION_ID: o ID da coleção.
LOCATION: a região em que você está usando a Vertex AI.
PROJECT_ID: o ID do projeto do Google Cloud .

Método HTTP e URL:

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

Corpo JSON da solicitação:

{
  "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"
  }
}

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI do gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections?collection_id=COLLECTION_ID"

PowerShell (Windows)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections?collection_id=COLLECTION_ID" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

{
  "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

Antes de usar os dados do comando abaixo, faça estas substituições:

DATA_SCHEMA_FILE: o caminho local para o arquivo de esquema de dados.
VECTOR_SCHEMA_FILE: o caminho local para o arquivo de esquema de vetor.
COLLECTION_ID: o ID da coleção.
LOCATION: a região em que você está usando a Vertex AI.
PROJECT_ID: o ID do projeto do Google Cloud .

Execute o seguinte comando:

Linux, macOS ou 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

Você receberá uma resposta semelhante a esta:

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()

No exemplo, uma solicitação é feita com collection_id definido como COLLECTION_ID e o seguinte como parte do corpo da solicitação:

data_schema: especifica a estrutura do objeto de dados.
vector_schema: configura e define os campos de vetor.

Todos os campos nos esquemas precisam ser definidos explicitamente. A opção de esquema JSON additionalProperties não é compatível.

Como receber uma coleta

O exemplo a seguir demonstra como receber uma referência a uma coleção com o ID COLLECTION_ID.

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

COLLECTION_ID: o ID da coleção.
LOCATION: a região em que você está usando a Vertex AI.
PROJECT_ID: o ID do projeto do Google Cloud .

Método HTTP e URL:

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

Corpo JSON da solicitação:

{
  "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"
  }
}

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID"

PowerShell (Windows)

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

{
  "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

Antes de usar os dados do comando abaixo, faça estas substituições:

COLLECTION_ID: o ID da coleção.
LOCATION: a região em que você está usando a Vertex AI.
PROJECT_ID: o ID do projeto do Google Cloud .

Execute o seguinte comando:

Linux, macOS ou 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

Você receberá uma resposta semelhante a esta:

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)

Listar coleções

O exemplo a seguir mostra como recuperar uma lista de coleções atuais.

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

LOCATION: a região em que você está usando a Vertex AI.
PROJECT_ID: o ID do projeto do Google Cloud .

Método HTTP e URL:

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

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Execute o seguinte comando:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections"

PowerShell (Windows)

Execute o seguinte comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

{
  "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

Antes de usar os dados do comando abaixo, faça estas substituições:

LOCATION: a região em que você está usando a Vertex AI.
PROJECT_ID: o ID do projeto do Google Cloud .

Execute o seguinte comando:

Linux, macOS ou 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

Você receberá uma resposta semelhante a esta:

---
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)

Atualizar uma coleção

O método UpdateCollection permite modificar um recurso de coleção atual. É possível controlar quais campos são atualizados usando update_mask. Se você não fornecer uma máscara de atualização, todos os campos presentes na solicitação de atualização vão substituir os campos correspondentes na coleção.

Os campos especificados na máscara de atualização são relativos ao recurso "Collection". Para substituir completamente todo o recurso "Collection" pelo fornecido na solicitação, use * como a máscara de atualização.

É possível atualizar os seguintes campos:

display_name
description
labels
data_schema
vector_schema

É possível fazer as seguintes atualizações para data_schema e vector_schema:

Adicionar campos.
Remova o campo vertex_embedding_config dos elementos vector_schema. Todos os outros campos não podem ser removidos.
Especifique um caminho de subcampo em update__mask para atualizar membros aninhados em data_schema e vector_schema. Exemplo:
- data_schema.properties.new_field
- vector_schema.my_vector_field

Excluir uma coleção

O exemplo a seguir demonstra como excluir uma Collection com o ID COLLECTION_ID.

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

COLLECTION_ID: o ID da coleção.
LOCATION: a região em que você está usando a Vertex AI.
PROJECT_ID: o ID do projeto do Google Cloud .

Método HTTP e URL:

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

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Execute o seguinte comando:

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID"

PowerShell (Windows)

Execute o seguinte comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

{
  "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

Antes de usar os dados do comando abaixo, faça estas substituições:

COLLECTION_ID: o ID da coleção.
LOCATION: a região em que você está usando a Vertex AI.
PROJECT_ID: o ID do projeto do Google Cloud .

Execute o seguinte comando:

Linux, macOS ou 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

Você receberá uma resposta semelhante a esta:

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()

A seguir

Saiba como criar objetos de dados para adicionar a uma coleção ou importar os dados do Cloud Storage.
Saiba como consultar e pesquisar objetos de dados.

Coleções Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Esquema de coleta

Criar uma coleção

REST

curl (Linux, macOS ou Cloud Shell)

PowerShell (Windows)

gcloud

Linux, macOS ou Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Python

Como receber uma coleta

REST

curl (Linux, macOS ou Cloud Shell)

PowerShell (Windows)

gcloud

Linux, macOS ou Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Python

Listar coleções

REST

curl (Linux, macOS ou Cloud Shell)

PowerShell (Windows)

gcloud

Linux, macOS ou Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Python

Atualizar uma coleção

Excluir uma coleção

REST

curl (Linux, macOS ou Cloud Shell)

PowerShell (Windows)

gcloud

Linux, macOS ou Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Python

A seguir

Coleções