‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

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

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

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

בנוסף לפונקציונליות של חיפוש 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	הפונקציה מתאימה לאובייקטים של נתונים עם ערכי שדות שמכילים טוקן שתואם לערך שצוין. האופרטור הזה זמין רק בארה"ב כשהוא משמש כחלק מחיפוש וקטורי באינדקס.	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": "*"
  }
}

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

‫Curl (Linux,‏ macOS או Cloud Shell)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login, או באמצעות Cloud Shell שמחבר אתכם אוטומטית ל-CLI של gcloud. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:

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/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:query"

‎PowerShell (Windows)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:

$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/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:query" | Select-Object -Expand Content

אתם אמורים לקבל תגובת 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)

הערה: אם משתמשים בפקודה ב-' לציטוט תוכן, צריך להחליף את הגרשיים במירכאות. אם הציטוט הוא חלק מרכיב בתוך רכיב, צריך להשתמש ב-\" כדי לסמן בתו בריחה (escape) את הציטוט הפנימי.

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

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

‫Curl (Linux,‏ macOS או Cloud Shell)

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:

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/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:aggregate"

‎PowerShell (Windows)

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:

$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/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:aggregate" | Select-Object -Expand Content

אתם אמורים לקבל תגובת 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)

מה השלב הבא?

איך מחפשים אובייקטים של נתונים

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

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

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

REST

‫Curl (Linux,‏ macOS או Cloud Shell)

‎PowerShell (Windows)

gcloud

‫Linux,‏ macOS או Cloud Shell

‏Windows (PowerShell)

Windows‏ (cmd.exe)

Python

REST

‫Curl (Linux,‏ macOS או Cloud Shell)

‎PowerShell (Windows)

gcloud

‫Linux,‏ macOS או Cloud Shell

‏Windows (PowerShell)

Windows‏ (cmd.exe)

Python

מה השלב הבא?

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