Collections

Dans Vector Search 2.0, les collections sont utilisées pour stocker les objets de données associés. Ils fournissent une source de vérité que vous pouvez interroger pour déterminer l'état exact des objets de données qu'ils contiennent.

Schéma de la collection

Lorsque vous créez une collection, vous devez fournir les schémas JSON suivants :

Un schéma de données, qui fournit la structure de vos données définie par l'utilisateur.
Schéma vectoriel qui définit et configure les champs vectoriels de vos objets de données.

Ensemble, ils sont appelés schéma de la collection.

Créer une collection

L'exemple suivant montre comment créer une collection avec l'ID COLLECTION_ID, en spécifiant à la fois un schéma de données et un schéma vectoriel.

REST

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

COLLECTION_ID : ID de la collection.
LOCATION : région dans laquelle vous utilisez Vertex AI.
PROJECT_ID : ID de votre projet Google Cloud .

Méthode HTTP et URL :

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

Corps JSON de la requête :

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

Pour envoyer votre requête, développez l'une des options suivantes :

curl (Linux, macOS ou Cloud Shell)

Remarque : La commande suivante suppose que vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login, ou en utilisant Cloud Shell, qui vous connecte automatiquement à la CLI gcloud. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

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

PowerShell (Windows)

Remarque : La commande suivante suppose que vous vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

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

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

Vous devriez recevoir une réponse JSON de ce type :

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

gcloud

Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :

DATA_SCHEMA_FILE : chemin d'accès local au fichier de schéma de données.
VECTOR_SCHEMA_FILE : chemin d'accès local au fichier de schéma vectoriel.
COLLECTION_ID : ID de la collection.
LOCATION : région dans laquelle vous utilisez Vertex AI.
PROJECT_ID : ID de votre projet Google Cloud .

Exécutez la commande suivante :

Linux, macOS ou Cloud Shell

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

Windows (PowerShell)

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

Windows (cmd.exe)

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

Vous devriez obtenir un résultat semblable à celui-ci :

Created collection [COLLECTION_ID].

Python

from google.cloud import vectorsearch_v1beta

# Create the client
vector_search_service_client = vectorsearch_v1beta.VectorSearchServiceClient()

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

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

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

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

Dans l'exemple, une requête est effectuée avec collection_id défini sur COLLECTION_ID et les éléments suivants dans le corps de la requête :

data_schema : spécifie la structure de l'objet de données.
vector_schema : configure et définit les champs de vecteur.

Tous les champs des schémas doivent être définis de manière explicite. L'option de schéma JSON additionalProperties n'est pas acceptée.

Obtenir une collection

L'exemple suivant montre comment obtenir une référence à une collection existante avec l'ID COLLECTION_ID.

REST

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

COLLECTION_ID : ID de la collection.
LOCATION : région dans laquelle vous utilisez Vertex AI.
PROJECT_ID : ID de votre projet Google Cloud .

Méthode HTTP et URL :

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

Corps JSON de la requête :

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

Pour envoyer votre requête, développez l'une des options suivantes :

curl (Linux, macOS ou Cloud Shell)

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

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

PowerShell (Windows)

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

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

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

Vous devriez recevoir une réponse JSON de ce type :

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

gcloud

Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :

COLLECTION_ID : ID de la collection.
LOCATION : région dans laquelle vous utilisez Vertex AI.
PROJECT_ID : ID de votre projet Google Cloud .

Exécutez la commande suivante :

Linux, macOS ou Cloud Shell

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

Windows (PowerShell)

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

Windows (cmd.exe)

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

Vous devriez obtenir un résultat semblable à celui-ci :

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

Python

from google.cloud import vectorsearch_v1beta

# Create the client
vector_search_service_client = vectorsearch_v1beta.VectorSearchServiceClient()

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

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

# Handle the response
print(response)

Collections de fiches

L'exemple suivant montre comment récupérer une liste de collections existantes.

REST

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

LOCATION : région dans laquelle vous utilisez Vertex AI.
PROJECT_ID : ID de votre projet Google Cloud .

Méthode HTTP et URL :

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

Pour envoyer votre requête, développez l'une des options suivantes :

curl (Linux, macOS ou Cloud Shell)

Exécutez la commande suivante :

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

PowerShell (Windows)

Exécutez la commande suivante :

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

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

Vous devriez recevoir une réponse JSON de ce type :

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

gcloud

Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :

LOCATION : région dans laquelle vous utilisez Vertex AI.
PROJECT_ID : ID de votre projet Google Cloud .

Exécutez la commande suivante :

Linux, macOS ou Cloud Shell

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

Windows (PowerShell)

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

Windows (cmd.exe)

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

Vous devriez obtenir un résultat semblable à celui-ci :

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

Python

from google.cloud import vectorsearch_v1beta

# Create the client
vector_search_service_client = vectorsearch_v1beta.VectorSearchServiceClient()

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

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

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

Modifier une collection

La méthode UpdateCollection vous permet de modifier une ressource Collection existante. Vous pouvez contrôler les champs à mettre à jour à l'aide de update_mask. Si vous ne fournissez pas de masque de mise à jour, tous les champs présents dans votre requête de mise à jour écraseront les champs correspondants de la collection.

Les champs spécifiés dans le masque de mise à jour sont relatifs à la ressource Collection. Pour remplacer complètement la ressource Collection par celle fournie dans la requête, utilisez * comme masque de mise à jour.

Vous pouvez modifier les champs suivants :

display_name
description
labels
data_schema
vector_schema

Vous pouvez apporter les modifications suivantes à data_schema et vector_schema :

Ajoutez des champs.
Supprimez le champ vertex_embedding_config des éléments vector_schema. Tous les autres champs ne peuvent pas être supprimés.
Spécifiez un chemin de sous-champ dans update__mask pour mettre à jour les membres imbriqués dans data_schema et vector_schema. Exemple :
- data_schema.properties.new_field
- vector_schema.my_vector_field

Supprimer une collection

L'exemple suivant montre comment supprimer une collection existante avec l'ID COLLECTION_ID.

REST

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

COLLECTION_ID : ID de la collection.
LOCATION : région dans laquelle vous utilisez Vertex AI.
PROJECT_ID : ID de votre projet Google Cloud .

Méthode HTTP et URL :

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

Pour envoyer votre requête, développez l'une des options suivantes :

curl (Linux, macOS ou Cloud Shell)

Exécutez la commande suivante :

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

PowerShell (Windows)

Exécutez la commande suivante :

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

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

Vous devriez recevoir une réponse JSON de ce type :

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

gcloud

Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :

COLLECTION_ID : ID de la collection.
LOCATION : région dans laquelle vous utilisez Vertex AI.
PROJECT_ID : ID de votre projet Google Cloud .

Exécutez la commande suivante :

Linux, macOS ou Cloud Shell

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

Windows (PowerShell)

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

Windows (cmd.exe)

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

Vous devriez obtenir un résultat semblable à celui-ci :

Deleted collection [COLLECTION_ID].

Python

from google.cloud import vectorsearch_v1beta

# Create the client
vector_search_service_client = vectorsearch_v1beta.VectorSearchServiceClient()

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

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

Étape suivante

Découvrez comment créer des objets de données à ajouter à une collection ou importer les données depuis Cloud Storage.
Découvrez comment interroger et rechercher des objets de données.

Collections Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Schéma de la collection

Créer une collection

REST

curl (Linux, macOS ou Cloud Shell)

PowerShell (Windows)

gcloud

Linux, macOS ou Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Python

Obtenir une collection

REST

curl (Linux, macOS ou Cloud Shell)

PowerShell (Windows)

gcloud

Linux, macOS ou Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Python

Collections de fiches

REST

curl (Linux, macOS ou Cloud Shell)

PowerShell (Windows)

gcloud

Linux, macOS ou Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Python

Modifier une collection

Supprimer une collection

REST

curl (Linux, macOS ou Cloud Shell)

PowerShell (Windows)

gcloud

Linux, macOS ou Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Python

Étape suivante

Collections