Objetos de dados

Na recuperação de agente (antiga pesquisa vetorial 2.0), as coleções armazenam dados como objetos JSON individuais chamados objetos de dados. Esta página descreve as regras de validação que um objeto de dados precisa atender e como criar, ler, atualizar, importar, exportar e excluir objetos de dados individualmente ou em lote.

Validação de dados

Cada objeto de dados ingerido pela recuperação de agente é verificado em relação a um conjunto fixo de regras. Se uma regra falhar para um registro, ele será rejeitado e emitido para o coletor de erros com code = INVALID_ARGUMENT. As verificações posteriores não serão executadas para esse registro. Para evitar o loop "corrigir um erro, ingerir novamente, encontrar o próximo erro", valide seu conjunto de dados com todas as regras de validação de dados antes de iniciar uma ingestão ou criação de índice.

O pipeline aplica as validações nesta ordem:

Fase O que ele verifica
1. Análise O JSON está bem formado, os campos obrigatórios de nível superior existem e os tipos de campo estão corretos.
2. Validações de ID O campo id está presente e corresponde ao formato de ID documentado.
3. Esquema do campo de dados O payload data está em conformidade com o esquema JSON declarado no CollectionConfig da coleção.
4. Validações de embeddings Cada vetor denso/esparso corresponde ao esquema de vetor da coleção (nome, tipo, dimensão, valores finitos, paridade esparsa e exclusividade).
5. População de campos pesquisáveis Os campos marcados como pesquisáveis no esquema podem ser extraídos de data

1. Validações de análise

As validações de análise são executadas primeiro, transformando cada linha de entrada em um objeto de dados interno. Eles se aplicam aos dois formatos JSON compatíveis: o padrão (com um objeto vectors/data de nível superior) e o v1 (com embedding, sparse_embedding, restricts ou numeric_restricts). O formato é detectado automaticamente por registro.

  • O JSON precisa ser analisável. Cada linha precisa ser analisada como um objeto JSON. Uma linha cujas chaves de nível superior não correspondem ao formato padrão nem ao v1 é rejeitada com Unknown JSON format for string: <line>.
  • id é obrigatório. Cada registro precisa conter um id não nulo. Caso contrário: 'id' field is missing or null.
  • Os embeddings precisam estar presentes (somente formato v1). Um registro no formato v1 precisa conter pelo menos um de embedding ou sparse_embedding. Caso contrário: 'embedding' or 'sparse_embedding' fields are missing.
  • Verificações de tipo de incorporação densa.O campo de incorporação densa (embedding na v1 ou qualquer valor de matriz em vectors no formato padrão) precisa ser uma matriz JSON de números. Um valor que não pode ser convertido em um float é rejeitado com '<field>' field contains non-float values.
  • Verificações de estrutura de embeddings esparsos. Para cada vetor esparso:
    • Precisa ser um objeto JSON.
    • Precisa conter as duas matrizes: values (floats) e indices (longs). Na v1, elas são values e dimensions.
    • values não pode ficar em branco.
    • Os índices não podem ser negativos.
    • values.length precisa ser igual a indices.length (ou dimensions.length da v1).
  • Tipo de campo data.Se presente, data precisa ser um objeto JSON, não uma matriz, string ou escalar. Caso contrário: 'data' field is not a JSON object.
  • Formato numeric_restricts (v1). numeric_restricts precisa ser uma matriz JSON de objetos. Cada entrada precisa ter uma string namespace e definir exatamente um de value_int, value_float ou value_double.

A maioria dos problemas de "primeira falha" vem dessa etapa. Erros comuns incluem um número em string em uma matriz de incorporação, um id ausente ou values/indices de comprimentos diferentes.

2. Validações de ID

Os IDs de objetos de dados precisam estar em conformidade com a RFC 1035. Na prática, isso significa:

  • Ter de 1 a 63 caracteres.
  • Somente letras minúsculas, dígitos e hífens (-). Não use maiúsculas, sublinhados, espaços, símbolos ou Unicode.
  • Precisa começar com uma letra minúscula (a-z).
  • Precisa terminar com uma letra minúscula ou um dígito (sem - no final).

Expressão regular: [a-z]([-a-z0-9]{0,61}[a-z0-9])?

A tabela a seguir mostra exemplos comuns:

ID Válida? Por quê?
doc-123 Sim Começa com uma letra, apenas minúsculas + dígitos + hífen, termina com um dígito
a Sim O mínimo é uma única letra minúscula.
product-sku-42 Sim Todas as regras atendidas
Doc-123 Não D em maiúsculas não permitido
123-doc Não Precisa começar com uma letra, não um dígito
doc_123 Não Sublinhado não permitido
doc-123- Não Não pode terminar com hífen
my doc Não Espaços não são permitidos
64 caracteres ou mais Não O tamanho máximo é 63

Essa forma é a regra de rótulo DNS (a parte entre pontos em um nome de host como my-service.example.com). Ela é reutilizada aqui para que os IDs façam o round-trip com segurança em URLs, nomes de arquivos, registros e CLIs sem escape.

3. Validações de campos de dados (JSON Schema)

A etapa de validação do campo de dados só é executada se a coleta tiver um dataSchema declarado no CollectionConfig. Se nenhum esquema for configurado, essa etapa será ignorada.

  • Conformidade com o esquema: o payload data do objeto de dados é serializado em JSON e validado com o esquema JSON configurado (rascunho 7). O validador informa um erro por violação de esquema. Portanto, um registro com três campos incorretos produz três mensagens de erro.
    • Mensagem: DataObject with id <id> failed schema validation: <error>.
  • Erros de processamento de esquema: se o próprio validador de esquema gerar um erro (por exemplo, recursos de rascunho não compatíveis), o registro será rejeitado com DataObject with id <id> failed schema validation processing: <exception>.

4. Validações de campo de embedding

A etapa de validação do campo de incorporação itera primeiro sobre vetores densos e depois sobre vetores esparsos. Um único conjunto compartilhado de nomes de vetores vistos abrange ambas as listas. Portanto, um nome não pode ser usado duas vezes, mesmo entre o limite denso e esparso.

Regras compartilhadas (aplicadas a dados densos e esparsos)

Regra Por que isso é importante Mensagem de erro
Não há nomes de vetores duplicados em vetores densos e esparsos para o mesmo objeto de dados Duas entradas com o mesmo nome de vetor segmentariam a mesma chave de armazenamento, produzindo um comportamento indefinido de "última gravação vence". ... has duplicate embedding field '<name>' across its dense/sparse vectors; each vector name must appear at most once
O nome do vetor precisa ser declarado no esquema de vetor CollectionConfig Um nome de vetor desconhecido não pode ser encaminhado para uma coluna ... has dense/sparse embedding field '<name>' but this field is not defined in CollectionConfig vector schema

Regras somente de vetor denso

Regra Mensagem de erro
O campo precisa ser configurado como dense no esquema de coleção. ... has dense embedding field '<name>' but CollectionConfig defines it as non-dense
A dimensão precisa corresponder à dimensão configurada. ... field '<name>': expected dense embedding dimension <expected>, but got <actual>
Todos os valores precisam ser finitos: sem NaN, +Infinity ou -Infinity. Valores não finitos corromperiam os cálculos de distância. ... field '<name>': dense embedding contains non-finite value <v> at index <i> (NaN/Infinity values are not allowed)

Regras somente de vetor esparso

Regra Mensagem de erro
O campo precisa ser configurado como sparse no esquema da coleção. ... has sparse embedding field '<name>' but CollectionConfig defines it as non-sparse
Paridade de comprimento de índices/valores: indicesCount == valuesCount. ... field '<name>': sparse embedding has <n> indices but <m> values; indices and values must have the same length
Índices não negativos: todo índice >= 0. ... field '<name>': sparse embedding contains negative index <i> at position <p> (indices must be non-negative)
Índices exclusivos no mesmo vetor esparso. ... field '<name>': sparse embedding contains duplicate index <i> (each index must appear at most once)
Todos os valores precisam ser finitos. ... field '<name>': sparse embedding contains non-finite value <v> at position <p> (NaN/Infinity values are not allowed)

5. População de campos pesquisáveis

Depois que a validação de incorporação for concluída, o pipeline vai percorrer o payload data usando o dataSchema da coleção e copiar os campos declarados pelo esquema (string, número inteiro/número, booleano, matriz de string e objetos aninhados) para um índice de campos pesquisáveis. Dois modos de falha aqui também vão rejeitar um registro:

  • Um caminho que deveria ser uma struct contém um escalar. Por exemplo, o esquema diz que author.name é uma string, mas author é uma string no documento.
  • Um campo de matriz de strings contém um elemento que não é uma string.

Normalmente, isso indica que o formato do documento divergiu do esquema declarado e nem sempre é detectado na etapa do esquema JSON.

Lista de verificação pré-execução

Antes de iniciar uma ingestão ou criação de índice, valide todo o conjunto de dados de acordo com as seguintes regras. Esse é o mesmo conjunto de verificações que o pipeline aplica, ordenado para que uma única transmissão do lado do cliente mostre todos os problemas:

  1. Formato: cada linha é analisada como JSON e corresponde ao formato padrão ou v1.
  2. IDs: correspondem à expressão regular RFC 1035 [a-z]([-a-z0-9]{0,61}[a-z0-9])? e são exclusivos em todo o conjunto de dados.
  3. Embeddings presentes: pelo menos um vetor por registro. Os nomes dos vetores são listados no esquema de vetor CollectionConfig com o tipo denso ou esparso correto.
  4. Vetores densos: dimensão correta, sem valores NaN, +Inf ou -Inf.
  5. Vetores esparsos: values.length == indices.length; todos os índices maiores ou iguais a 0 e exclusivos. Valores não finitos não são permitidos.
  6. Não há nomes de vetores duplicados em um registro em dados densos e esparsos.
  7. Esquema de dados: se um dataSchema estiver configurado, o payload data será validado com base nele (Draft 7), e o tipo JSON real de cada campo vai corresponder ao tipo declarado (especialmente para objetos aninhados e matrizes de strings).
  8. v1 numeric_restricts: cada entrada tem uma string namespace e exatamente um dos seguintes valores: value_int / value_float / value_double.

Criar um objeto de dados

O exemplo a seguir demonstra como adicionar um único objeto de dados 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:

  • DATA_OBJECT_ID: o ID do objeto de dados.
  • COLLECTION_ID: o ID da coleção.
  • LOCATION: a região em que você está usando a plataforma de agentes.
  • PROJECT_ID: o ID do projeto do Google Cloud .

Método HTTP e URL: 

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

Corpo JSON da solicitação:

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

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

Você receberá uma resposta JSON semelhante a esta:

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

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

  • DATA_FILE: o caminho local para um arquivo JSON que contém a parte de dados do objeto de dados.

    Exemplo de conteúdo do arquivo:

    {
  "director": "Frank Darabont",
  "genre": "Drama",
  "title": "The Shawshank Redemption",
  "year": 1994
}
  • VECTORS_FILE: o caminho local para um arquivo JSON que contém os vetores do objeto de dados.

    Exemplo de conteúdo do arquivo:

    {
  "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: o ID do objeto de dados.
  • COLLECTION_ID: o ID da coleção.
  • LOCATION: a região em que você está usando a plataforma de agentes.
  • PROJECT_ID: o ID do projeto do Google Cloud .

Execute o seguinte comando:

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

Você receberá uma resposta semelhante a esta:

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)

Os campos de incorporação que têm uma incorporação automática especificada no esquema da coleção são preenchidos automaticamente. Também é possível trazer suas próprias incorporações (BYOE) para definir valores de campo de vetor que não são preenchidos automaticamente.

Criar objetos de dados em lote

Para ingestão em massa eficiente de um pequeno número de registros (até 1.000 objetos de dados por solicitação), use batchCreate. Todo o lote é atômico: ou todos os objetos de dados são criados, ou toda a solicitação falha. Para conjuntos de dados maiores, prefira importar objetos de dados do Cloud Storage.

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 plataforma de agentes.
  • PROJECT_ID: o ID do projeto do Google Cloud .

Método HTTP e URL: 

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

Corpo JSON da solicitação:

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

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

Você receberá uma resposta JSON semelhante a esta:

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

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 plataforma de agentes.
  • PROJECT_ID: o ID do projeto do Google Cloud .

Execute o seguinte comando:

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

Receber um objeto de dados

O exemplo a seguir demonstra como receber um objeto de dados com o ID DATA_OBJECT_ID de 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:

  • DATA_OBJECT_ID: o ID do objeto de dados.
  • COLLECTION_ID: o ID da coleção.
  • LOCATION: a região em que você está usando a plataforma de agentes.
  • PROJECT_ID: o ID do projeto do Google Cloud .

Método HTTP e URL: 

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

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

Você receberá uma resposta JSON semelhante a esta:

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

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

  • DATA_OBJECT_ID: o ID do objeto de dados.
  • COLLECTION_ID: o ID da coleção.
  • LOCATION: a região em que você está usando a plataforma de agentes.
  • PROJECT_ID: o ID do projeto do Google Cloud .

Execute o seguinte comando:

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

Você receberá uma resposta semelhante a esta:

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)

Atualizar um objeto de dados

O exemplo a seguir demonstra como atualizar o campo de dados title e os valores de vetor plot_embedding no objeto de dados com o ID DATA_OBJECT_ID em 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:

  • DATA_OBJECT_ID: o ID do objeto de dados.
  • COLLECTION_ID: o ID da coleção.
  • LOCATION: a região em que você está usando a plataforma de agentes.
  • PROJECT_ID: o ID do projeto do Google Cloud .

Método HTTP e URL: 

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

Corpo JSON da solicitação:

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

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

Você receberá uma resposta JSON semelhante a esta:

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

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

  • DATA_OBJECT_ID: o ID do objeto de dados.
  • COLLECTION_ID: o ID da coleção.
  • LOCATION: a região em que você está usando a plataforma de agentes.
  • PROJECT_ID: o ID do projeto do Google Cloud .

Execute o seguinte comando:

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

Você receberá uma resposta semelhante a esta:

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)

Atualização em lote de objetos de dados

Para atualizar vários objetos de dados de uma só vez, use batchUpdate. No máximo, 1.000 objetos de dados podem ser atualizados em um único lote. Cada solicitação por registro especifica o dataObject (que precisa incluir o name completo do recurso e os campos que você quer mudar) e uma updateMask que lista quais campos substituir. Os campos não listados na máscara permanecem inalterados.

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 plataforma de agentes.
  • PROJECT_ID: o ID do projeto do Google Cloud .

Método HTTP e URL: 

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

Corpo JSON da solicitação:

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

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

Você receberá uma resposta JSON semelhante a esta:

{}

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 plataforma de agentes.
  • PROJECT_ID: o ID do projeto do Google Cloud .

Execute o seguinte comando:

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

Importar objetos de dados

O exemplo a seguir demonstra como importar objetos de dados do Cloud Storage para uma coleção com o ID COLLECTION_ID. Use a importação para conjuntos de dados grandes. Para ingestões em massa menores (até 1.000 registros), considere criar objetos de dados em lote.

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 plataforma de agentes.
  • PROJECT_ID: o ID do projeto do Google Cloud .

Método HTTP e URL: 

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

Corpo JSON da solicitação:

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

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

Você receberá uma resposta JSON semelhante a esta:

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

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 plataforma de agentes.
  • PROJECT_ID: o ID do projeto do Google Cloud .

Execute o seguinte comando:

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

A pasta gs://your-bucket/path/to/your-data/ pode conter um ou mais arquivos, cada um com vários objetos de dados. Use essa estrutura para grandes conjuntos de dados distribuídos em vários arquivos. Os seguintes formatos de arquivo são compatíveis com a recuperação de agente:

  • JSONL, em que cada linha é um objeto JSON com três propriedades de nível superior: id, data e vectors. Use esse formato para novos conjuntos de dados de recuperação de agente quando quiser uma entrada legível por humanos para inspeção e edição manual.
  • AVRO: use esse formato para novos conjuntos de dados de recuperação de agente quando precisar de um formato binário compacto e validado por esquema, geralmente para conjuntos de dados grandes produzidos por ferramentas de pipeline de dados, como Dataflow, Beam ou Spark.
  • JSON da pesquisa vetorial: use esse formato apenas ao migrar um conjunto de dados JSON da pesquisa vetorial (pesquisa vetorial 1.0) e quiser reutilizá-lo como está.
  • AVRO da pesquisa vetorial: use esse formato apenas ao migrar um conjunto de dados AVRO da pesquisa vetorial (pesquisa vetorial 1.0) e quiser reutilizá-lo como está.

Confira a seguir um exemplo do JSONL com as propriedades necessárias.

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

Para arquivos AVRO, cada registro precisa estar em conformidade com o esquema DataObject mostrado. Os campos refletem o formato JSONL:

  • id (obrigatório string).
  • vectors (map, padrão {}). Cada entrada é identificada pelo nome do vetor, e o valor é um array de float (vetor denso) ou um registro SparseVector com values (matriz de float) e indices (matriz de long).
  • data (map anulável, padrão null). As chaves são nomes de campos de dados. Cada valor é um registro DataValue cujo campo value é uma união dos tipos primitivos compatíveis (boolean, int, long, float, double, string) mais array de DataValue e map de string para DataValue em estruturas aninhadas.
  • etag (aceita nulo string, padrão 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
    }
  ]
}

O snippet a seguir mostra o conteúdo conceitual de um único registro AVRO que corresponde ao exemplo JSONL anterior. Nesse esquema, cada entrada em data é encapsulada em um registro DataValue (com um único campo value), que é como o AVRO representa os tipos heterogêneos em 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 }
      }
    }
  }
}

Exportar objetos de dados

O exemplo a seguir demonstra como exportar todos os objetos de dados em uma coleção para o Cloud Storage no formato JSONL. O bucket de destino precisa estar na mesma região que a coleta. A exportação é uma operação de longa duração.

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 plataforma de agentes.
  • PROJECT_ID: o ID do projeto do Google Cloud .

Método HTTP e URL: 

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

Corpo JSON da solicitação:

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

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

Você receberá uma resposta JSON semelhante a esta:

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

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 plataforma de agentes.
  • PROJECT_ID: o ID do projeto do Google Cloud .

Execute o seguinte comando:

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

Excluir um objeto de dados

O exemplo a seguir mostra como excluir um único objeto de dados DATA_OBJECT_ID de 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:

  • DATA_OBJECT_ID: o ID do objeto de dados.
  • COLLECTION_ID: o ID da coleção.
  • LOCATION: a região em que você está usando a plataforma de agentes.
  • PROJECT_ID: o ID do projeto do Google Cloud .

Método HTTP e URL: 

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

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

Você receberá uma resposta JSON semelhante a esta:

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

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

  • DATA_OBJECT_ID: o ID do objeto de dados.
  • COLLECTION_ID: o ID da coleção.
  • LOCATION: a região em que você está usando a plataforma de agentes.
  • PROJECT_ID: o ID do projeto do Google Cloud .

Execute o seguinte comando:

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

Você receberá uma resposta semelhante a esta:

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)

Excluir objetos de dados em lote

Para excluir vários objetos de dados de uma só vez, use batchDelete com uma lista de nomes de recursos de objetos de dados totalmente qualificados. É possível excluir no máximo 1.000 objetos de dados em um único lote.

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 plataforma de agentes.
  • PROJECT_ID: o ID do projeto do Google Cloud .

Método HTTP e URL: 

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

Corpo JSON da solicitação:

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

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

Você receberá uma resposta JSON semelhante a esta:

{}

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 plataforma de agentes.
  • PROJECT_ID: o ID do projeto do Google Cloud .

Execute o seguinte comando:

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

Contar objetos de dados

Para contar quantos objetos de dados uma coleção contém, use a operação aggregate com o método de agregação COUNT. A mesma chamada aceita uma expressão de filtro JSON opcional para que você possa contar apenas os objetos de dados que correspondem a um predicado (por exemplo, genre == "sci-fi").

Para contar todos os objetos de dados na coleção, omita o filtro.

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 plataforma de agentes.
  • PROJECT_ID: o ID do projeto do Google Cloud .

Método HTTP e URL: 

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

Corpo JSON da solicitação:

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

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

Você receberá uma resposta JSON semelhante a esta:

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

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 plataforma de agentes.
  • PROJECT_ID: o ID do projeto do Google Cloud .

Execute o seguinte comando:

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

A seguir