Objetos de datos

En la Recuperación de agentes (anteriormente, Vector Search 2.0), las colecciones almacenan datos como objetos JSON individuales llamados objetos de datos. En esta página, se describen las reglas de validación que debe satisfacer un objeto de datos y cómo crear, leer, actualizar, importar, exportar y borrar objetos de datos de forma individual o por lotes.

Validación de datos

Cada objeto de datos que ingiere la recuperación del agente se verifica con un conjunto fijo de reglas. Si alguna regla falla para un registro, se rechaza y se emite al receptor de errores con code = INVALID_ARGUMENT. Las verificaciones posteriores no se ejecutan para ese registro. Para evitar el ciclo de "corregir un error, volver a transferir, encontrar el siguiente error", valida tu conjunto de datos con todas las reglas de validación de datos antes de iniciar una transferencia o una compilación de índice.

La canalización aplica las validaciones en este orden:

Etapa Qué verifica
1. Análisis El formato JSON es correcto, existen los campos obligatorios de nivel superior y los tipos de campos son correctos.
2. Validaciones de ID El campo id está presente y coincide con el formato de ID documentado.
3. Esquema del campo de datos La carga útil de data cumple con el esquema JSON declarado en el CollectionConfig de la colección.
4. Validaciones de incorporación Cada vector denso o vector disperso coincide con el esquema de vectores de la colección (nombre, tipo, dimensión, valores finitos, paridad dispersa y unicidad).
5. Población de campos aptos para la búsqueda Los campos marcados como aptos para la búsqueda en el esquema se pueden extraer correctamente de data.

1. Validaciones de análisis

Las validaciones de análisis se ejecutan primero, mientras se convierte cada línea de entrada en un objeto de datos interno. Se aplican a ambas formas de JSON admitidas, el formato predeterminado (con un objeto vectors/data de nivel superior) y el formato v1 (con embedding, sparse_embedding, restricts o numeric_restricts). El formato se detecta automáticamente por registro.

  • El formato JSON debe ser analizable. Cada línea debe analizarse como un objeto JSON. Se rechaza con Unknown JSON format for string: <line> una línea cuyas claves de nivel superior no coinciden con el formato predeterminado ni con el de la versión 1.
  • id es obligatorio. Cada registro debe contener un id no nulo. De lo contrario, se mostrará el error 'id' field is missing or null.
  • Los embeddings deben estar presentes (solo en el formato v1). Un registro en formato v1 debe contener al menos uno de los campos embedding o sparse_embedding. De lo contrario, se mostrará el error 'embedding' or 'sparse_embedding' fields are missing.
  • Verificaciones de tipo de la incorporación densa. El campo de incorporación densa (embedding en la versión 1 o cualquier valor de array en vectors en el formato predeterminado) debe ser un array de números en formato JSON. Se rechaza con '<field>' field contains non-float values un valor que no se puede convertir en un float.
  • Verificaciones de la estructura de la incorporación dispersa. Para cada vector disperso, se realizan las siguientes verificaciones:
    • Debe ser un objeto JSON.
    • Debe contener ambos arrays: values (números de punto flotante) y indices (números enteros largos). En la versión 1, estos son values y dimensions.
    • values no debe estar vacío.
    • Los índices no deben ser negativos.
    • values.length debe ser igual a indices.length (o dimensions.length en la versión 1).
  • Tipo de campo data: Si está presente, data debe ser un objeto JSON, no un array, una cadena o un escalar. De lo contrario, 'data' field is not a JSON object.
  • Forma numeric_restricts (formato v1). numeric_restricts debe ser un array JSON de objetos. Cada entrada debe tener una cadena namespace y debe establecer exactamente uno de value_int, value_float o value_double.

La mayoría de los problemas de "primera falla" provienen de esta etapa. Entre los errores comunes, se incluyen un número convertido en cadena en un array de incorporación, la falta de id o values/indices de diferentes longitudes.

2. Validaciones de ID

Los IDs de objetos de datos deben cumplir con RFC 1035. En la práctica, esto significa lo siguiente:

  • Debe tener entre 1 y 63 caracteres.
  • Solo letras minúsculas, dígitos y guiones (-) No se permiten mayúsculas, guiones bajos, espacios, símbolos ni Unicode.
  • Debe comenzar con una letra en minúscula (a-z).
  • Debe terminar con una letra minúscula o un dígito (sin - al final).

Expresión regular: [a-z]([-a-z0-9]{0,61}[a-z0-9])?

En la siguiente tabla, se muestran ejemplos comunes:

ID ¿Es válida? Por qué
doc-123 Sí Comienza con una letra, solo letras en minúscula, números y guiones, y termina con un número
a Sí Se requiere al menos una letra minúscula.
product-sku-42 Sí Se cumplen todas las reglas
Doc-123 No No se permite D en mayúsculas
123-doc No Debe comenzar con una letra, no con un dígito.
doc_123 No No se permite el guion bajo
doc-123- No No puede terminar con un guion.
my doc No No se permiten espacios
Más de 64 caracteres No La longitud máxima es de 63.

Esta forma es la regla de etiqueta de DNS (la parte entre puntos en un nombre de host como my-service.example.com). Se reutiliza aquí para que los IDs se transfieran de forma segura a través de URLs, nombres de archivos, registros y CLI sin necesidad de escapar.

3. Validaciones de campos de datos (esquema JSON)

La etapa de validación de campos de datos solo se ejecuta si la recopilación tiene un dataSchema declarado en su CollectionConfig. Si no se configura ningún esquema, se omite esta etapa.

  • Cumplimiento del esquema: La carga útil data del objeto de datos se serializa en JSON y se valida con el esquema JSON (borrador 7) configurado. El validador informa un error por cada incumplimiento del esquema, por lo que un registro con tres campos incorrectos genera tres mensajes de error.
    • Mensaje: DataObject with id <id> failed schema validation: <error>.
  • Errores de procesamiento del esquema. Si el propio validador de esquemas arroja un error (por ejemplo, si se usan funciones de borrador no admitidas), el registro se rechaza con DataObject with id <id> failed schema validation processing: <exception>.

4. Validaciones de campos de incorporación

La etapa de validación de campos de incorporación primero itera sobre los vectores densos y, luego, sobre los vectores dispersos. Un solo conjunto compartido de nombres de vectores vistos abarca ambas listas, por lo que un nombre no se puede usar dos veces, ni siquiera entre el límite denso y disperso.

Reglas compartidas (se aplican a los datos densos y dispersos)

Regla Por qué es importante Mensaje de error
No se permiten nombres de vectores duplicados en los vectores densos y dispersos para el mismo objeto de datos. Dos entradas con el mismo nombre de vector se orientarían a la misma clave de almacenamiento, lo que produciría un comportamiento indefinido de la última escritura gana. ... has duplicate embedding field '<name>' across its dense/sparse vectors; each vector name must appear at most once
Se debe declarar el nombre del vector en el esquema del vector CollectionConfig Un nombre de vector desconocido no se puede enrutar a una columna ... has dense/sparse embedding field '<name>' but this field is not defined in CollectionConfig vector schema

Reglas solo de vectores densos

Regla Mensaje de error
El campo debe configurarse como denso en el esquema de la colección. ... has dense embedding field '<name>' but CollectionConfig defines it as non-dense
La dimensión debe coincidir con la dimensión configurada. ... field '<name>': expected dense embedding dimension <expected>, but got <actual>
Todos los valores deben ser finitos, sin NaN, +Infinity ni -Infinity. Los valores no finitos dañarían los cálculos de distancia. ... field '<name>': dense embedding contains non-finite value <v> at index <i> (NaN/Infinity values are not allowed)

Reglas solo para vectores dispersos

Regla Mensaje de error
El campo debe configurarse como sparse en el esquema de la colección. ... has sparse embedding field '<name>' but CollectionConfig defines it as non-sparse
Paridad de longitud de índices y valores: indicesCount == valuesCount. ... field '<name>': sparse embedding has <n> indices but <m> values; indices and values must have the same length
Índices no negativos: Todos los índices >= 0. ... field '<name>': sparse embedding contains negative index <i> at position <p> (indices must be non-negative)
Índices únicos dentro del mismo vector disperso ... field '<name>': sparse embedding contains duplicate index <i> (each index must appear at most once)
Todos los valores deben ser finitos. ... field '<name>': sparse embedding contains non-finite value <v> at position <p> (NaN/Infinity values are not allowed)

5. Población de campos aptos para la búsqueda

Una vez que se valida la incorporación, la canalización recorre la carga útil de data con el dataSchema de la colección y copia los campos que declara el esquema (cadena, número entero/número, booleano, array de cadena y objetos anidados) en un índice de campos aptos para la búsqueda. Aquí, dos modos de falla también rechazarán un registro:

  • Una ruta de acceso que debería ser una struct contiene un escalar (por ejemplo, el esquema indica que author.name es una cadena, pero author es en sí misma una cadena en el documento).
  • Un campo de array de cadenas contiene un elemento que no es una cadena.

Por lo general, indican que la forma del documento se desvió del esquema declarado y no siempre se detectan en la etapa del esquema JSON.

Lista de tareas previa a la transición

Antes de iniciar una indexación o una compilación de índice, valida todo el conjunto de datos según las siguientes reglas. Este es el mismo conjunto de verificaciones que aplica la canalización, ordenado de modo que una sola pasada del cliente muestre todos los problemas:

  1. Formato: Cada línea se analiza como JSON y coincide con la forma predeterminada o la versión 1.
  2. IDs: Coinciden con la expresión regular RFC 1035 [a-z]([-a-z0-9]{0,61}[a-z0-9])? y son únicos en todo el conjunto de datos.
  3. Embeddings presentes: Al menos un vector por registro. Los nombres de los vectores se indican en el esquema de vectores CollectionConfig con el tipo denso o disperso correcto.
  4. Vectores densos: Dimensión correcta; no hay valores de NaN, +Inf ni -Inf.
  5. Vectores dispersos: values.length == indices.length; todos los índices deben ser mayores o iguales que 0 y únicos. No se permiten valores no finitos.
  6. No se permiten nombres de vectores duplicados en un registro en los vectores densos y dispersos.
  7. Esquema de datos: Si se configura un dataSchema, tu carga útil de data se valida en función de él (borrador 7), y el tipo JSON real de cada campo coincide con el tipo declarado (especialmente para los objetos anidados y los arrays de cadenas).
  8. v1 numeric_restricts: Cada entrada tiene una cadena namespace y exactamente uno de los siguientes elementos: value_int, value_float o value_double.

Crea un objeto de datos

En el siguiente ejemplo, se muestra cómo agregar un solo objeto de datos a una colección con el ID COLLECTION_ID.

REST

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • DATA_OBJECT_ID: Es el ID del objeto de datos.
  • COLLECTION_ID: ID de la colección.
  • LOCATION: Es la región en la que usas Agent Platform.
  • PROJECT_ID: Tu Google Cloud ID del proyecto.

Método HTTP y URL: 

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

Cuerpo JSON de la solicitud:

{
  "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 tu solicitud, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "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 cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:

  • DATA_FILE: Es la ruta de acceso local a un archivo JSON que contiene la parte de datos del objeto de datos.

    Ejemplo de contenido del archivo:

    {
  "director": "Frank Darabont",
  "genre": "Drama",
  "title": "The Shawshank Redemption",
  "year": 1994
}
  • VECTORS_FILE: Es la ruta de acceso local a un archivo JSON que contiene los vectores que forman parte del objeto de datos.

    Ejemplo de contenido del archivo:

    {
  "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: Es el ID del objeto de datos.
  • COLLECTION_ID: ID de la colección.
  • LOCATION: Es la región en la que usas Agent Platform.
  • PROJECT_ID: Tu Google Cloud ID del proyecto.

Ejecuta el siguiente comando:

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

Deberías recibir una respuesta similar a la que figura a continuación:

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)

Los campos de incorporación que tienen una incorporación automática especificada en el esquema de la colección se propagan automáticamente. También puedes proporcionar tus propias incorporaciones (BYOE) para establecer valores de campos vectoriales que no se completan automáticamente.

Crea objetos de datos por lotes

Para la transferencia masiva eficiente de una pequeña cantidad de registros (hasta 1,000 objetos de datos por solicitud), usa batchCreate. Todo el lote es atómico: o se crean todos los objetos de datos o falla toda la solicitud. Para conjuntos de datos más grandes, es mejor importar objetos de datos desde Cloud Storage.

REST

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • COLLECTION_ID: ID de la colección.
  • LOCATION: Es la región en la que usas Agent Platform.
  • PROJECT_ID: Tu Google Cloud ID del proyecto.

Método HTTP y URL: 

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

Cuerpo JSON de la solicitud:

{
  "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 tu solicitud, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "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 cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:

  • COLLECTION_ID: ID de la colección.
  • LOCATION: Es la región en la que usas Agent Platform.
  • PROJECT_ID: Tu Google Cloud ID del proyecto.

Ejecuta el siguiente comando:

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

Obtén un objeto de datos

En el siguiente ejemplo, se muestra cómo obtener un objeto de datos con el ID DATA_OBJECT_ID de una colección con el ID COLLECTION_ID.

REST

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • DATA_OBJECT_ID: Es el ID del objeto de datos.
  • COLLECTION_ID: ID de la colección.
  • LOCATION: Es la región en la que usas Agent Platform.
  • PROJECT_ID: Tu Google Cloud ID del proyecto.

Método HTTP y URL: 

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

Para enviar tu solicitud, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "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 cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:

  • DATA_OBJECT_ID: Es el ID del objeto de datos.
  • COLLECTION_ID: ID de la colección.
  • LOCATION: Es la región en la que usas Agent Platform.
  • PROJECT_ID: Tu Google Cloud ID del proyecto.

Ejecuta el siguiente comando:

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

Deberías recibir una respuesta similar a la que figura a continuación:

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)

Actualiza un objeto de datos

En el siguiente ejemplo, se muestra cómo actualizar el campo de datos title y los valores del vector plot_embedding en el objeto de datos con el ID DATA_OBJECT_ID en una colección con el ID COLLECTION_ID.

REST

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • DATA_OBJECT_ID: Es el ID del objeto de datos.
  • COLLECTION_ID: ID de la colección.
  • LOCATION: Es la región en la que usas Agent Platform.
  • PROJECT_ID: Tu Google Cloud ID del proyecto.

Método HTTP y URL: 

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

Cuerpo JSON de la solicitud:

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

Para enviar tu solicitud, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "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 cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:

  • DATA_OBJECT_ID: Es el ID del objeto de datos.
  • COLLECTION_ID: ID de la colección.
  • LOCATION: Es la región en la que usas Agent Platform.
  • PROJECT_ID: Tu Google Cloud ID del proyecto.

Ejecuta el siguiente comando:

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

Deberías recibir una respuesta similar a la que figura a continuación:

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)

Actualización por lotes de objetos de datos

Para actualizar muchos objetos de datos a la vez, usa batchUpdate. Se puede actualizar un máximo de 1,000 objetos de datos en un solo lote. Cada solicitud por registro especifica el dataObject (que debe incluir su name de recurso completo más los campos que deseas cambiar) y un listado updateMask de los campos que se deben reemplazar. Los campos que no se enumeran en la máscara permanecen sin cambios.

REST

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • COLLECTION_ID: ID de la colección.
  • LOCATION: Es la región en la que usas Agent Platform.
  • PROJECT_ID: Tu Google Cloud ID del proyecto.

Método HTTP y URL: 

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

Cuerpo JSON de la solicitud:

{
  "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 tu solicitud, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{}

gcloud

Antes de usar cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:

  • COLLECTION_ID: ID de la colección.
  • LOCATION: Es la región en la que usas Agent Platform.
  • PROJECT_ID: Tu Google Cloud ID del proyecto.

Ejecuta el siguiente comando:

Linux, macOS o 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 datos

En el siguiente ejemplo, se muestra cómo importar objetos de datos de Cloud Storage a una colección con el ID COLLECTION_ID. Usa la importación para conjuntos de datos grandes. Para las incorporaciones masivas más pequeñas (hasta 1,000 registros), considera crear objetos de datos en lotes.

REST

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • COLLECTION_ID: ID de la colección.
  • LOCATION: Es la región en la que usas Agent Platform.
  • PROJECT_ID: Tu Google Cloud ID del proyecto.

Método HTTP y URL: 

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

Cuerpo JSON de la solicitud:

{
  "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 tu solicitud, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "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 cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:

  • COLLECTION_ID: ID de la colección.
  • LOCATION: Es la región en la que usas Agent Platform.
  • PROJECT_ID: Tu Google Cloud ID del proyecto.

Ejecuta el siguiente comando:

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

La carpeta gs://your-bucket/path/to/your-data/ puede contener uno o más archivos, cada uno con varios objetos de datos. Usa esta estructura para los conjuntos de datos grandes que se distribuyen en varios archivos. Los siguientes formatos de archivo son compatibles con la recuperación de agentes:

  • JSONL, en el que cada línea es un objeto JSON que tiene tres propiedades de nivel superior: id, data y vectors. Usa este formato para los conjuntos de datos nuevos de recuperación del agente cuando quieras una entrada legible por humanos para inspeccionar y editar manualmente.
  • AVRO: Usa este formato para los conjuntos de datos nuevos de Agent Retrieval cuando necesites un formato binario compacto y validado por esquema, generalmente para conjuntos de datos grandes producidos por herramientas de canalización de datos, como Dataflow, Beam o Spark.
  • JSON de Vector Search: Usa este formato solo cuando migres un conjunto de datos JSON existente de Vector Search (Vector Search 1.0) y quieras reutilizarlo tal como está.
  • AVRO de Vector Search: Usa este formato solo cuando migres un conjunto de datos AVRO existente de Vector Search (Vector Search 1.0) y quieras reutilizarlo tal como está.

A continuación, se proporciona un ejemplo del archivo JSONL con las propiedades requeridas.

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

En el caso de los archivos AVRO, cada registro debe cumplir con el esquema de Avro DataObject que se muestra. Los campos reflejan el formato JSONL:

  • id (obligatorio string).
  • vectors (map, valor predeterminado {}). Cada entrada se indexa por el nombre del vector y su valor es un array de float (vector denso) o un registro SparseVector con values (matriz de float) y indices (matriz de long).
  • data (map que admite valores nulos, null predeterminado). Las claves son nombres de campos de datos. Cada valor es un registro DataValue cuyo campo value es una unión sobre los tipos primitivos admitidos (boolean, int, long, float, double, string) más array de DataValue y map de string a DataValue para estructuras anidadas.
  • etag (string que admite valores nulos, valor predeterminado 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
    }
  ]
}

En el siguiente fragmento, se muestra el contenido conceptual de un solo registro de AVRO que coincide con el ejemplo de JSONL anterior. Ten en cuenta que, según este esquema, cada entrada en data se incluye en un registro de DataValue (con un solo campo de value), que es la forma en que AVRO representa los tipos heterogéneos en 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 datos

En el siguiente ejemplo, se muestra cómo exportar cada objeto de datos de una colección a Cloud Storage en formato JSONL. El bucket de destino debe estar en la misma región que la colección. La exportación es una operación de larga duración.

REST

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • COLLECTION_ID: ID de la colección.
  • LOCATION: Es la región en la que usas Agent Platform.
  • PROJECT_ID: Tu Google Cloud ID del proyecto.

Método HTTP y URL: 

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

Cuerpo JSON de la solicitud:

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

Para enviar tu solicitud, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "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 cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:

  • COLLECTION_ID: ID de la colección.
  • LOCATION: Es la región en la que usas Agent Platform.
  • PROJECT_ID: Tu Google Cloud ID del proyecto.

Ejecuta el siguiente comando:

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

Borra un objeto de datos

En el siguiente ejemplo, se muestra cómo borrar un solo objeto de datos DATA_OBJECT_ID de una colección con el ID COLLECTION_ID.

REST

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • DATA_OBJECT_ID: Es el ID del objeto de datos.
  • COLLECTION_ID: ID de la colección.
  • LOCATION: Es la región en la que usas Agent Platform.
  • PROJECT_ID: Tu Google Cloud ID del proyecto.

Método HTTP y URL: 

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

Para enviar tu solicitud, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "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 cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:

  • DATA_OBJECT_ID: Es el ID del objeto de datos.
  • COLLECTION_ID: ID de la colección.
  • LOCATION: Es la región en la que usas Agent Platform.
  • PROJECT_ID: Tu Google Cloud ID del proyecto.

Ejecuta el siguiente comando:

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

Deberías recibir una respuesta similar a la que figura a continuación:

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)

Borra por lotes objetos de datos

Para borrar muchos objetos de datos a la vez, usa batchDelete con una lista de nombres de recursos de objetos de datos completamente calificados. Se puede borrar un máximo de 1,000 objetos de datos en un solo lote.

REST

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • COLLECTION_ID: ID de la colección.
  • LOCATION: Es la región en la que usas Agent Platform.
  • PROJECT_ID: Tu Google Cloud ID del proyecto.

Método HTTP y URL: 

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

Cuerpo JSON de la solicitud:

{
  "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 tu solicitud, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{}

gcloud

Antes de usar cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:

  • COLLECTION_ID: ID de la colección.
  • LOCATION: Es la región en la que usas Agent Platform.
  • PROJECT_ID: Tu Google Cloud ID del proyecto.

Ejecuta el siguiente comando:

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

Recuento de objetos de datos

Para contar cuántos objetos de datos contiene una colección, usa la operación aggregate con el método de agregación COUNT. La misma llamada acepta una expresión de filtro JSON opcional para que puedas contar solo los objetos de datos que coinciden con un predicado (por ejemplo, genre == "sci-fi").

Para contar todos los objetos de datos de la colección, omite el filtro.

REST

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • COLLECTION_ID: ID de la colección.
  • LOCATION: Es la región en la que usas Agent Platform.
  • PROJECT_ID: Tu Google Cloud ID del proyecto.

Método HTTP y URL: 

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

Cuerpo JSON de la solicitud:

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

Para enviar tu solicitud, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

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

gcloud

Antes de usar cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:

  • COLLECTION_ID: ID de la colección.
  • LOCATION: Es la región en la que usas Agent Platform.
  • PROJECT_ID: Tu Google Cloud ID del proyecto.

Ejecuta el siguiente comando:

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

Próximos pasos