Sammlungen nach Datenobjekten durchsuchen

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

Sprache des Filterausdrucks

Zusätzlich zur KNN-/ANN-Suchfunktion bietet Agent Retrieval vielseitige Abfragemöglichkeiten mit einer benutzerdefinierten Abfragesprache. Die Abfragesprache wird in der folgenden Tabelle erläutert.

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

Sammlungen abfragen

Im folgenden Beispiel wird gezeigt, wie Sie mit einem Filter nach Datenobjekten in einer Sammlung mit der ID COLLECTION_ID suchen.

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)

Für die Aggregation verwenden Sie den Endpunkt aggregate und geben 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