Objetos de datos

En Agent Retrieval (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

La recuperación de agentes (anteriormente, Vector Search 2.0) valida cada objeto de datos antes de almacenarlo. La validación se realiza en dos contextos que aplican las mismas reglas básicas, pero difieren en la forma en que se informan los errores:

Contexto Se aplica a Comportamiento en caso de error
Validación de objetos de datos Escrituras individuales y por lotes: create, batchCreate, update y batchUpdate La solicitud falla de inmediato con INVALID_ARGUMENT. Las escrituras por lotes son atómicas: si algún registro no es válido, no se escribe ningún registro de la solicitud.
Validación de importaciones import desde Cloud Storage Cada registro se valida de forma independiente. Se escribe un registro no válido en el receptor de errores con code = INVALID_ARGUMENT, se omite y continúa el resto de la importación. Una vez que un registro no pasa una verificación, no se ejecutan las verificaciones posteriores para ese registro.

Ambos contextos aplican las mismas reglas principales: reglas de ID, reglas de campos de datos (cuando la colección declara un dataSchema) y reglas de incorporación. La importación también analiza cada registro y extrae campos aptos para la búsqueda, ya que su entrada son archivos sin procesar en lugar de solicitudes estructuradas a la API.

Para evitar un bucle de "corregir un error, volver a procesar, encontrar el siguiente error", valida tu conjunto de datos según todas las reglas que se indican a continuación antes de comenzar una importación o una compilación de índice.

Análisis (solo para importar)

El análisis solo se aplica a la importación, que convierte cada línea o registro de entrada sin procesar en un objeto de datos interno. Las escrituras de API individuales y por lotes omiten este paso porque su entrada ya está estructurada. El análisis controla 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.
  • Se requiere id. Cada registro debe contener un id no nulo. De lo contrario, 'id' field is missing or null.
  • Las incorporaciones 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, 'embedding' or 'sparse_embedding' fields are missing.
  • Verificaciones de tipo de 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 JSON de números. Un valor que no se puede convertir en un float se rechaza con '<field>' field contains non-float values.
  • Verificaciones de la estructura de embeddings dispersos. Para cada vector disperso, haz lo siguiente:
    • 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. En caso contrario, usa '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.

Reglas de ID

El ID de objeto de datos debe tener entre 1 y 63 caracteres. La longitud es la única restricción que la Recuperación del agente aplica a un ID; se aceptan todos los caracteres.

En la siguiente tabla, se muestran ejemplos comunes:

ID ¿Es válida? Por qué
movie-789 Sí Debe tener entre 1 y 63 caracteres.
a Sí Se requiere al menos un carácter.
Doc_123 Sí Se permiten letras mayúsculas y guiones bajos.
my doc Sí Se acepta cualquier carácter dentro del límite de longitud.
(string vacía) No Se requiere al menos un carácter
64 caracteres o más No La longitud máxima es de 63.

Reglas de campos de datos (esquema JSON)

La validación de campos de datos solo se ejecuta si la colección declara un dataSchema en su CollectionConfig. Si no se configura ningún esquema, se omitirá esta verificación.

  • 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>.

Reglas de incorporación

La validación de la incorporación itera primero 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)

Extracción de campos aptos para la búsqueda (solo importación)

Durante la importación, después de que se realiza correctamente la validación de 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 cada problema:

  1. Formato: Cada línea se analiza como JSON y coincide con la forma predeterminada o la versión 1.
  2. IDs: Tienen entre 1 y 63 caracteres, 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 a 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: Es el 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 la parte de vectores 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: Es el 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 completan 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: Es el 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: Es el 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: Es el 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: Es el 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: Es el 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: Es el 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 no se modifican.

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: Es el 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: Es el 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)

Importa 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: Es el 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: Es el 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á.

JSONL

En el siguiente ejemplo, se muestra el formato JSONL con las propiedades requeridas. Cada línea del archivo de entrada es un solo objeto de datos con las propiedades de nivel superior id, data y vectors.

{
  "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 AVRO que coincide con el ejemplo de JSONL anterior. Ten en cuenta que, en este esquema, cada entrada de data se incluye en un registro DataValue (con un solo campo 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: Es el 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: Es el 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: Es el 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: Es el 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: Es el 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: Es el 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: Es el 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: Es el 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