Sammlungen nach Datenobjekten durchsuchen

Mit der Query API können Datenobjekte mithilfe eines Filters aus einer Sammlung abgerufen werden. Das ist vergleichbar mit dem Abfragen einer Datenbanktabelle und der Verwendung einer SQL-WHERE-Klausel. Sie können die Aggregation auch verwenden, um die Anzahl der Datenobjekte zu ermitteln, die einem Filter entsprechen.

Sprache des Filterausdrucks

Zusätzlich zur KNN-/ANN-Suchfunktion bietet der Agentenabruf vielseitige Abfragefunktionen mit einer benutzerdefinierten Abfragesprache. Die Abfragesprache wird in der folgenden Tabelle erläutert.

Filter Beschreibung Unterstützte Datentypen Beispiel
$eq Gleicht Datenobjekte mit Feldwerten ab, die einem angegebenen Wert entsprechen. Zahl, String, boolescher Wert {"genre": {"$eq": "documentary"}}
$ne Gleicht Datenobjekte mit Feldwerten ab, die nicht mit einem angegebenen Wert übereinstimmen. Zahl, String, boolescher Wert {"genre": {"$ne": "drama"}}
$gt Gleicht Datenobjekte mit Feldwerten ab, die größer als ein angegebener Wert sind. Zahl {"year": {"$gt": 2019}}
$gte Gleicht Datenobjekte mit Feldwerten ab, die größer oder gleich einem angegebenen Wert sind. Zahl {"year": {"$gte": 2020}}
$lt Gleicht Datenobjekte mit Feldwerten ab, die kleiner als ein angegebener Wert sind. Zahl {"year": {"$lt": 2020}}
$lte Gleicht Datenobjekte mit Feldwerten ab, die kleiner oder gleich einem angegebenen Wert sind. Zahl {"year": {"$lte": 2020}}
$in Gleicht Datenobjekte mit Feldwerten ab, die in einem angegebenen Array enthalten sind. String {"genre": {"$in": ["comedy", "documentary"]}}
$nin Gleicht Datenobjekte mit Feldwerten ab, die nicht in einem angegebenen Array enthalten sind. String {"genre": {"$nin": ["comedy", "documentary"]}}
$and Verknüpft Abfrageklauseln mit einem logischen AND. - {"$and": [{"genre": {"$eq": "drama"}}, {"year": {"$gte": 2020}}]}
$or Verknüpft Abfrageklauseln mit einem logischen OR. - {"$or": [{"genre": {"$eq": "drama"}}, {"year": {"$gte": 2020}}]}
$all Wählt die Dokumente aus, bei denen der Arraywert eines Felds alle angegebenen Werte enthält. - {"colors": {"$all": ["red", "blue"]}}
$search Gleicht Datenobjekte mit Feldwerten ab, die ein Token enthalten, das mit einem angegebenen Wert übereinstimmt. Dieser Operator ist nur in der Multiregion „us“ verfügbar, wenn er als Teil der Vektorsuche in einem Index verwendet wird. String {"content": {"$search": "blue"}}

Sammlungen abfragen

Im folgenden Beispiel wird gezeigt, wie Sie einen Filter verwenden, um Datenobjekte in einer Sammlung mit der ID COLLECTION_ID abzufragen.

REST

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • COLLECTION_ID: Die ID der Sammlung.
  • LOCATION: Die Region, in der Sie die Agent Platform verwenden.
  • PROJECT_ID: Ihre Google Cloud Projekt-ID.

HTTP-Methode und URL: 

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

JSON-Text anfordern:

{
  "page_size": 10,
  "page_token": "",
  "filter": {
    "$or": [
      {
        "director": {
          "$eq": "Akira Kurosawa"
        }
      },
      {
        "$and": [
          {
            "director": {
              "$eq": "David Fincher"
            }
          },
          {
            "genre": {
              "$ne": "Thriller"
            }
          }
        ]
      }
    ]
  },
  "output_fields": {
    "data_fields": "*",
    "vector_fields": "*",
    "metadata_fields": "*"
  }
}

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:

{
  "dataObjects": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/1",
      "createTime": "2026-02-04T14:35:29Z",
      "updateTime": "2026-02-04T14:37:29Z",
      "data": {
        "title": "Seven Samurai",
        "director": "Akira Kurosawa",
        "genre": "Action",
        "year": 1954
      },
      "vectors": {
        "genre_embedding": {
          "dense": {
            "values": [
              0.3863801,
              0.73934346,
              0.16189057,
              0.5271367
            ]
          }
        },
        "sparse_embedding": {
          "sparse": {
            "values": [
              1,
              6,
              3,
              2,
              8,
              5,
              2
            ],
            "indices": [
              4065,
              13326,
              17377,
              25918,
              28105,
              32683,
              42998
            ]
          }
        },
        "plot_embedding": {
          "dense": {
            "values": [
              1,
              1,
              1
            ]
          }
        },
        "soundtrack_embedding": {
          "dense": {
            "values": [
              0.5920452,
              0.08301644,
              0.12647335,
              0.619643,
              0.49258286
            ]
          }
        }
      }
    },
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/2",
      "createTime": "2026-02-04T15:35:29Z",
      "updateTime": "2026-02-04T15:37:29Z",
      "data": {
        "title": "The Social Network",
        "director": "David Fincher",
        "genre": "Drama",
        "year": 2010
      },
      "vectors": {
        "genre_embedding": {
          "dense": {
            "values": [
              0.1,
              0.2,
              0.3,
              0.4
            ]
          }
        },
        "sparse_embedding": {
          "sparse": {
            "values": [
              1
            ],
            "indices": [
              1000
            ]
          }
        },
        "plot_embedding": {
          "dense": {
            "values": [
              0.1,
              0.1,
              0.1
            ]
          }
        },
        "soundtrack_embedding": {
          "dense": {
            "values": [
              0.1,
              0.2,
              0.3,
              0.4,
              0.5
            ]
          }
        }
      }
    }
  ]
}

gcloud

Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

  • COLLECTION_ID: Die ID der Sammlung.
  • LOCATION: Die Region, in der Sie die Agent Platform verwenden.
  • PROJECT_ID: Ihre Google Cloud Projekt-ID.

Führen Sie folgenden Befehl aus:

Linux, macOS oder Cloud Shell

gcloud vector-search collections data-objects query \
  --json-filter='{"$or": [{"director": {"$eq": "Akira Kurosawa"}},{"$and": [{"director": {"$eq": "David Fincher"}},{"genre": {"$ne": "Thriller"}}]}]}' \
  --output-data-fields='*' \
  --output-vector-fields='*' \
  --output-metadata-fields='*' \
  --collection=COLLECTION_ID \
  --location=LOCATION \
  --project=PROJECT_ID

Windows (PowerShell)

gcloud vector-search collections data-objects query `
  --json-filter='{"$or": [{"director": {"$eq": "Akira Kurosawa"}},{"$and": [{"director": {"$eq": "David Fincher"}},{"genre": {"$ne": "Thriller"}}]}]}' `
  --output-data-fields='*' `
  --output-vector-fields='*' `
  --output-metadata-fields='*' `
  --collection=COLLECTION_ID `
  --location=LOCATION `
  --project=PROJECT_ID

Windows (cmd.exe)

gcloud vector-search collections data-objects query ^
  --json-filter='{"$or": [{"director": {"$eq": "Akira Kurosawa"}},{"$and": [{"director": {"$eq": "David Fincher"}},{"genre": {"$ne": "Thriller"}}]}]}' ^
  --output-data-fields='*' ^
  --output-vector-fields='*' ^
  --output-metadata-fields='*' ^
  --collection=COLLECTION_ID ^
  --location=LOCATION ^
  --project=PROJECT_ID

Sie sollten eine Antwort ähnlich der folgenden erhalten:

---
createTime: '2026-02-04T14:35:29Z'
data:
  director: Akira Kurosawa
  genre: Action
  title: Seven Samurai
  year: 1954
name: projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/1
updateTime: '2026-02-04T14:37:29Z'
vectors:
  genre_embedding:
    dense:
      values:
      - 0.38638
      - 0.739343
      - 0.161891
      - 0.527137
  plot_embedding:
    dense:
      values:
      - 1.0
      - 1.0
      - 1.0
  soundtrack_embedding:
    dense:
      values:
      - 0.592045
      - 0.0830164
      - 0.126473
      - 0.619643
      - 0.492583
  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
---
createTime: '2026-02-04T15:35:29Z'
data:
  director: David Fincher
  genre: Drama
  title: The Social Network
  year: 2010
name: projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/2
updateTime: '2026-02-04T15:37:29Z'
vectors:
  genre_embedding:
    dense:
      values:
      - 0.1
      - 0.2
      - 0.3
      - 0.4
  plot_embedding:
    dense:
      values:
      - 0.1
      - 0.1
      - 0.1
  soundtrack_embedding:
    dense:
      values:
      - 0.1
      - 0.2
      - 0.3
      - 0.4
      - 0.5
  sparse_embedding:
    sparse:
      indices:
      - 1000
      values:
      - 1.0

Python

from google.cloud import vectorsearch_v1

# Create the client
data_object_search_service_client = vectorsearch_v1.DataObjectSearchServiceClient()

# Initialize request
request = vectorsearch_v1.QueryDataObjectsRequest(
    parent="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
    filter={
        "$or": [
            {"director": {"$eq": "Akira Kurosawa"}},
            {
                "$and": [
                    {"director": {"$eq": "David Fincher"}},
                    {"genre": {"$ne": "Thriller"}},
                ]
            },
        ]
    },
)

# Make the request
page_result = data_object_search_service_client.query_data_objects(request=request)

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

Wenn Sie eine Aggregation ausführen möchten, verwenden Sie den Endpunkt aggregate und geben Sie den Aggregationstyp im Anfragetext an.

Im folgenden Beispiel wird gezeigt, wie Sie alle Datenobjekte in einer Sammlung mit der ID COLLECTION_ID zählen.

REST

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • COLLECTION_ID: Die ID der Sammlung.
  • LOCATION: Die Region, in der Sie die Agent Platform verwenden.
  • PROJECT_ID: Ihre Google Cloud Projekt-ID.

HTTP-Methode und URL: 

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

JSON-Text anfordern:

{
  "aggregate": "count"
}

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:

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

gcloud

Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

  • COLLECTION_ID: Die ID der Sammlung.
  • LOCATION: Die Region, in der Sie die Agent Platform verwenden.
  • PROJECT_ID: Ihre Google Cloud Projekt-ID.

Führen Sie folgenden Befehl aus:

Linux, macOS oder Cloud Shell

gcloud vector-search collections data-objects aggregate \
  --aggregation-method=count \
  --collection=COLLECTION_ID \
  --location=LOCATION \
  --project=PROJECT_ID

Windows (PowerShell)

gcloud vector-search collections data-objects aggregate `
  --aggregation-method=count `
  --collection=COLLECTION_ID `
  --location=LOCATION `
  --project=PROJECT_ID

Windows (cmd.exe)

gcloud vector-search collections data-objects aggregate ^
  --aggregation-method=count ^
  --collection=COLLECTION_ID ^
  --location=LOCATION ^
  --project=PROJECT_ID

Sie sollten eine Antwort ähnlich der folgenden erhalten:

aggregateResults:
- count: 1000

Python

from google.cloud import vectorsearch_v1

# Create the client
data_object_search_service_client = vectorsearch_v1.DataObjectSearchServiceClient()

# Initialize request
request = vectorsearch_v1.AggregateDataObjectsRequest(
    parent="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
    aggregate="COUNT",
)

# Make the request
response = data_object_search_service_client.aggregate_data_objects(request=request)

# Handle the response
print(response)

Nächste Schritte