שליחת שאילתות לקולקציות של אובייקטים של נתונים

מטרת ה-Query API היא לאחזר אובייקטים של נתונים מאוסף באמצעות מסנן. זה דומה להרצת שאילתה על טבלה במסד נתונים ושימוש בסעיף WHERE ב-SQL. אפשר גם להשתמש בצבירה כדי לקבל ספירה של אובייקטי נתונים שתואמים למסנן.

שפת ביטוי הסינון

בנוסף לפונקציונליות של חיפוש KNN/ANN, ‏Agent Retrieval מספק יכולות שאילתה מגוונות באמצעות שפת שאילתות בהתאמה אישית. בטבלה הבאה מוסברת שפת השאילתה.

מסנן תיאור הסוגים הנתמכים דוגמה
$eq התאמה לאובייקטים של נתונים עם ערכי שדות ששווים לערך שצוין. מספר, מחרוזת, ערך בוליאני {"genre": {"$eq": "documentary"}}
‎$ne התאמה של אובייקטי נתונים עם ערכי שדות שלא שווים לערך שצוין. מספר, מחרוזת, ערך בוליאני {"genre": {"$ne": "drama"}}
$gt התאמה לאובייקטים של נתונים עם ערכי שדות שגדולים מהערך שצוין. מספר {"year": {"$gt": 2019}}
$gte התאמה לאובייקטים של נתונים עם ערכי שדות שגדולים מערך מסוים או שווים לו. מספר {"year": {"$gte": 2020}}
$lt התאמה לאובייקטי נתונים עם ערכי שדות שקטנים מהערך שצוין. מספר {"year": {"$lt": 2020}}
‎$lte התאמה לאובייקטי נתונים עם ערכי שדות שקטנים מערך מסוים או שווים לו. מספר {"year": {"$lte": 2020}}
$in התאמה לאובייקטים של נתונים עם ערכי שדות שנמצאים במערך שצוין. String {"genre": {"$in": ["comedy", "documentary"]}}
$nin התאמה של אובייקטי נתונים עם ערכי שדות שלא נמצאים במערך שצוין. String {"genre": {"$nin": ["comedy", "documentary"]}}
$and מצרף סעיפי שאילתה עם AND לוגי. - {"$and": [{"genre": {"$eq": "drama"}}, {"year": {"$gte": 2020}}]}
‎$or מחבר בין חלקי השאילתה באמצעות OR לוגי. - {"$or": [{"genre": {"$eq": "drama"}}, {"year": {"$gte": 2020}}]}
$all בוחר את המסמכים שבהם ערך המערך של שדה מכיל את כל הערכים שצוינו. - {"colors": {"$all": ["red", "blue"]}}
$search התאמה לאובייקטים של נתונים עם ערכי שדות שמכילים אסימון שתואם לערך שצוין. האופרטור הזה זמין רק באזור us multiregion כשמשתמשים בו כחלק מחיפוש וקטורי באינדקס. String {"content": {"$search": "blue"}}

שליחת שאילתות לאוספים

הדוגמה הבאה ממחישה איך להשתמש במסנן כדי לשלוח שאילתה על אובייקטים של נתונים באוסף עם המזהה COLLECTION_ID.

REST

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • ‫COLLECTION_ID: המזהה של האוסף.
  • ‫LOCATION: האזור שבו אתם משתמשים ב-Agent Platform.
  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .

ה-method של ה-HTTP וכתובת ה-URL:

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

תוכן בקשת JSON:

{
  "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": "*"
  }
}

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

אתם אמורים לקבל תגובת JSON שדומה לזו:

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

לפני השימוש בנתוני הפקודה הבאים, צריך להחליף את הנתונים הבאים:

  • ‫COLLECTION_ID: המזהה של האוסף.
  • ‫LOCATION: האזור שבו אתם משתמשים ב-Agent Platform.
  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .

מריצים את הפקודה הבאה:

‫Linux,‏ macOS או 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

אמורים לקבל תגובה שדומה לזו:

---
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)

כדי לבצע צבירה, משתמשים בנקודת הקצה aggregate ומציינים את סוג הצבירה בגוף הבקשה.

בדוגמה הבאה אפשר לראות איך סופרים את כל אובייקטי הנתונים באוסף עם המזהה COLLECTION_ID.

REST

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • ‫COLLECTION_ID: המזהה של האוסף.
  • ‫LOCATION: האזור שבו אתם משתמשים ב-Agent Platform.
  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .

ה-method של ה-HTTP וכתובת ה-URL:

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

תוכן בקשת JSON:

{
  "aggregate": "count"
}

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

אתם אמורים לקבל תגובת JSON שדומה לזו:

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

gcloud

לפני השימוש בנתוני הפקודה הבאים, צריך להחליף את הנתונים הבאים:

  • ‫COLLECTION_ID: המזהה של האוסף.
  • ‫LOCATION: האזור שבו אתם משתמשים ב-Agent Platform.
  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .

מריצים את הפקודה הבאה:

‫Linux,‏ macOS או 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

אמורים לקבל תגובה שדומה לזו:

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)

מה השלב הבא?