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

ב-Agent Retrieval (שנקרא בעבר Vector Search 2.0), נתונים מאוחסנים ב-Collections כאובייקטים נפרדים של JSON שנקראים Data Objects. בדף הזה מוסבר אילו כללי אימות צריכים להתקיים באובייקט נתונים, ואיך ליצור, לקרוא, לעדכן, לייבא, לייצא ולמחוק אובייקטים של נתונים בנפרד או בקבוצות.

אימות נתונים

הסוכן מאחזר (לשעבר Vector Search 2.0) ומאמת כל אובייקט נתונים לפני שהוא מאחסן אותו. האימות מתבצע בשני הקשרים שבהם נאכפים אותם כללי ליבה, אבל יש הבדל באופן הדיווח על כשלים:

הקשר חל על התנהגות במקרה של כשל
אימות של אובייקט נתונים כתיבה של פריטים בודדים ושל קבוצות פריטים: create,‏ batchCreate,‏ update ו-batchUpdate הבקשה נכשלת באופן מיידי עם השגיאה INVALID_ARGUMENT. פעולות כתיבה בקבוצות הן אטומיות: אם רשומה כלשהי לא תקינה, אף רשומה בבקשה לא תיכתב.
אימות ייבוא ‫import מ-Cloud Storage כל רשומה מאומתת בנפרד. רשומה לא תקינה נכתבת ליעד השגיאות עם code = INVALID_ARGUMENT ומדלגים עליה, והשאר של הייבוא ממשיך. אם רשומה נכשלת בבדיקה, לא יבוצעו עבורה בדיקות נוספות.

בשני ההקשרים נאכפים אותם כללי ליבה: כללי מזהה, כללים של שדות נתונים (כשהקולקציה מציינת dataSchema) וכללי הטמעה. הייבוא מנתח כל רשומה ומחפש שדות שאפשר לחפש בהם, כי הקלט שלו הוא קבצים גולמיים ולא בקשות API מובנות.

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

ניתוח (ייבוא בלבד)

הניתוח חל רק על ייבוא, שבו כל שורה או רשומה של קלט גולמי הופכת לאובייקט נתונים פנימי. בכתיבות API פרטניות ובכתיבות API של קבוצות, השלב הזה לא מתבצע כי הקלט כבר מובנה. הניתוח מטפל בשני פורמטים נתמכים של JSON: פורמט ברירת המחדל (עם אובייקט ברמה העליונה vectors/data) ופורמט v1 (עם embedding,‏ sparse_embedding,‏ restricts או numeric_restricts). המערכת מזהה את הפורמט באופן אוטומטי לכל רשומה.

  • חייב להיות אפשר לנתח את ה-JSON. כל שורה חייבת להיות ניתנת לניתוח כאובייקט JSON. שורה שהמפתחות ברמה העליונה שלה לא תואמים לפורמט ברירת המחדל או לפורמט v1 נדחית עם Unknown JSON format for string: <line>.
  • חובה לציין את id. כל רשומה צריכה להכיל ערך id שאינו null. אחרת: 'id' field is missing or null.
  • חייבים להיות הטמעות (בפורמט v1 בלבד). רשומה בפורמט v1 צריכה להכיל לפחות אחד מהערכים embedding או sparse_embedding. אחרת: 'embedding' or 'sparse_embedding' fields are missing.
  • בדיקות של סוגי הטמעה צפופים. שדה ההטמעה הצפופה (embedding בגרסה v1, או כל ערך של מערך ב-vectors בפורמט ברירת המחדל) חייב להיות מערך JSON של מספרים. ערך שלא ניתן להמיר ל-float נדחה עם '<field>' field contains non-float values.
  • בדיקות של מבנה הטמעה דליל. לכל וקטור דליל:
    • חייב להיות אובייקט JSON.
    • הוא חייב להכיל את שני המערכים: values (מספרים ממשיים) ו-indices (מספרים שלמים ארוכים). בגרסה 1 אלה הם values ו-dimensions.
    • חובה למלא את השדה: values.
    • האינדקסים לא יכולים להיות שליליים.
    • ‫values.length חייב להיות שווה ל-indices.length (או ל-v1 dimensions.length).
  • סוג השדה data. אם השדה הזה קיים, data חייב להיות אובייקט JSON, ולא מערך, מחרוזת או סקלר. אחרת: 'data' field is not a JSON object.
  • numeric_restricts צורה (פורמט v1). הערך numeric_restricts חייב להיות מערך JSON של אובייקטים. לכל רשומה צריך להיות מחרוזת namespace, וצריך להגדיר בדיוק אחד מהערכים value_int, value_float או value_double.

רוב הבעיות שקשורות ל'כשל ראשון' מתרחשות בשלב הזה. שגיאות נפוצות כוללות מספר שמוצג כמחרוזת במערך של הטמעה, חוסר של id או values/indices באורכים שונים.

כללי מזהה

מזהה של אובייקט נתונים צריך להיות באורך של 1 עד 63 תווים. האילוץ היחיד שמוטל על מזהה על ידי Agent Retrieval הוא האורך שלו. כל התווים מתקבלים.

בטבלה הבאה מוצגות דוגמאות נפוצות:

מזהה תקין? למה לבחור ב-
movie-789 כן בין 1 ל-63 תווים
a כן האורך המינימלי הוא תו אחד
Doc_123 כן מותר להשתמש באותיות רישיות ובקווים תחתונים
my doc כן אפשר להשתמש בכל תו, כל עוד לא חורגים ממגבלת האורך
(מחרוזת ריקה) לא חובה להזין לפחות תו אחד
‫64 תווים או יותר לא האורך המקסימלי הוא 63

כללים של שדות נתונים (סכימת JSON)

אימות של שדה נתונים מופעל רק אם האוסף מכריז על dataSchema ב-CollectionConfig שלו. אם לא מוגדר סכימה, הבדיקה הזו מדלגת.

  • עמידה בדרישות הסכימה. המטען הייעודי (payload) של אובייקט הנתונים data עובר סריאליזציה ל-JSON ומאומת בהתאם לסכימת ה-JSON שהוגדרה (גרסה 7). הכלי לאימות מדווח על שגיאה אחת לכל הפרה של הסכימה, כך שרשומה עם שלושה שדות שגויים תפיק שלוש הודעות שגיאה.
    • הודעה: DataObject with id <id> failed schema validation: <error>.
  • שגיאות עיבוד של סכימה. אם מאמת הסכימה עצמו יוצר חריגה (לדוגמה, תכונות טיוטה לא נתמכות), הרשומה נדחית עם DataObject with id <id> failed schema validation processing: <exception>.

הטמעה של כללים

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

כללים משותפים (חלים על נתונים צפופים ודלילים)

כלל למה זה חשוב הודעת השגיאה
אין שמות וקטורים כפולים בצפיפות ובדלילות לאותו אובייקט נתונים שתי רשומות עם אותו שם וקטור יפנו לאותו מפתח אחסון, ויגרמו להתנהגות לא מוגדרת של 'הכתיבה האחרונה קובעת' ... has duplicate embedding field '<name>' across its dense/sparse vectors; each vector name must appear at most once
צריך להצהיר על שם הווקטור בסכימת הווקטור CollectionConfig אי אפשר להפנות שם וקטור לא ידוע לעמודה ... has dense/sparse embedding field '<name>' but this field is not defined in CollectionConfig vector schema

כללים שמתבססים רק על וקטורים צפופים

כלל הודעת השגיאה
צריך להגדיר את השדה כ-dense בסכימת האוסף. ... has dense embedding field '<name>' but CollectionConfig defines it as non-dense
המאפיין חייב להיות זהה למאפיין שהוגדר. ... field '<name>': expected dense embedding dimension <expected>, but got <actual>
כל הערכים חייבים להיות סופיים – אסור להשתמש בערכים NaN,‏ +Infinity או -Infinity. ערכים לא סופיים עלולים לשבש את חישובי המרחק. ... field '<name>': dense embedding contains non-finite value <v> at index <i> (NaN/Infinity values are not allowed)

כללים שמתייחסים רק לווקטורים דלילים

כלל הודעת השגיאה
צריך להגדיר את השדה כsparse בסכימת האוסף. ... has sparse embedding field '<name>' but CollectionConfig defines it as non-sparse
אורך האינדקסים/הערכים זהה: indicesCount == valuesCount. ... field '<name>': sparse embedding has <n> indices but <m> values; indices and values must have the same length
אינדקסים לא שליליים: כל אינדקס >= 0. ... field '<name>': sparse embedding contains negative index <i> at position <p> (indices must be non-negative)
אינדקסים ייחודיים באותו וקטור דליל. ... field '<name>': sparse embedding contains duplicate index <i> (each index must appear at most once)
כל הערכים חייבים להיות סופיים. ... field '<name>': sparse embedding contains non-finite value <v> at position <p> (NaN/Infinity values are not allowed)

חילוץ שדות שניתנים לחיפוש (ייבוא בלבד)

במהלך הייבוא, אחרי שהטמעת האימות מסתיימת בהצלחה, צינור הנתונים עובר על מטען הנתונים data באמצעות dataSchema של האוסף ומעתיק שדות שהסכימה מצהירה עליהם (מחרוזת, מספר שלם/מספר, בוליאני, מערך של מחרוזות ואובייקטים מוטמעים) לאינדקס של שדות שאפשר לחפש בהם. שתי שיטות כושלות גם יגרמו לדחיית רשומה:

  • נתיב שאמור להיות מבנה מכיל סקלר (לדוגמה, הסכימה מציינת ש-author.name הוא מחרוזת, אבל author הוא מחרוזת בעצמו במסמך).
  • שדה של מערך מחרוזות מכיל רכיב שאינו מחרוזת.

בדרך כלל הן מציינות שהצורה של המסמך חרגה מהסכימה שהוגדרה, ולא תמיד הן מזוהות בשלב של סכימת ה-JSON.

רשימת המשימות לפני ההפעלה

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

  1. ‫Format – כל שורה מנותחת כ-JSON ותואמת לצורה שמוגדרת כברירת מחדל או לצורה v1.
  2. מזהים – באורך של תו אחד עד 63 תווים, וייחודיים בכל מערך הנתונים.
  3. הטמעות קיימות – לפחות וקטור אחד לכל רשומה; שמות הווקטורים מפורטים בסכימת הווקטורים CollectionConfig עם הסוג הנכון (דחוס או דליל).
  4. ווקטורים צפופים – ממד נכון; אין ערכים של NaN, +Inf או -Inf.
  5. Sparse vectors -- values.length == indices.length; all indexes greater or equal to 0 and unique. אסור להשתמש בערכים לא סופיים.
  6. אין שמות וקטורים כפולים ברשומה, גם אם היא דחוסה וגם אם היא דלילה.
  7. סכימת נתונים – אם מוגדר dataSchema, המטען הייעודי (payload) של data מאומת מולו (טיוטה 7), וסוג ה-JSON בפועל של כל שדה תואם לסוג המוצהר (במיוחד לאובייקטים מקוננים ולמערכים של מחרוזות).
  8. ‫v1 numeric_restricts – לכל רשומה יש מחרוזת namespace ואחת מהמחרוזות value_int / value_float / value_double.

יצירת אובייקט נתונים

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

REST

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

  • ‫DATA_OBJECT_ID: המזהה של אובייקט הנתונים.
  • ‫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?dataObjectId=DATA_OBJECT_ID

תוכן בקשת JSON: 

{
  "data": {
    "director": "Frank Darabont",
    "genre": "Drama",
    "title": "The Shawshank Redemption",
    "year": 1994
  },
  "vectors":{
    "genre_embedding": {
      "dense": {
        "values": [ 0.38638010860523064, 0.739343471733759, 0.16189056837017107, 0.5271366865924485 ]
      }
    },
    "plot_embedding": {
      "dense": {
        "values": [ 0.4752082440607731, 0.09026746166854707, 0.8752307753619009 ]
      }
    },
    "soundtrack_embedding": {
      "dense": {
        "values": [ 0.5920451749052875, 0.08301644173787519, 0.1264733498775969, 0.6196429624200321, 0.4925828581737443 ]
      }
    },
    "sparse_embedding": {
      "sparse": {
        "indices": [ 4065, 13326, 17377, 25918, 28105, 32683, 42998 ],
        "values": [ 1, 6, 3, 2, 8, 5, 2 ]
      }
    }
  }
}

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

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

{
  "name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/DATA_OBJECT_ID",
  "data": {
    "director": "Frank Darabont",
    "title": "The Shawshank Redemption",
    "year": 1994,
    "genre": "Drama"
  },
  "vectors": {
    "genre_embedding": {
      "dense": {
        "values": [
          0.3863801,
          0.73934346,
          0.16189057,
          0.5271367
        ]
      }
    },
    "plot_embedding": {
      "dense": {
        "values": [
          0.47520825,
          0.090267465,
          0.8752308
        ]
      }
    },
    "soundtrack_embedding": {
      "dense": {
        "values": [
          0.5920452,
          0.08301644,
          0.12647335,
          0.619643,
          0.49258286
        ]
      }
    },
    "sparse_embedding": {
      "sparse": {
        "values": [
          1,
          6,
          3,
          2,
          8,
          5,
          2
        ],
        "indices": [
          4065,
          13326,
          17377,
          25918,
          28105,
          32683,
          42998
        ]
      }
    }
  }
}

gcloud

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

  • ‫DATA_FILE: הנתיב המקומי לקובץ JSON שמכיל את חלק הנתונים של אובייקט הנתונים.

    תוכן קובץ לדוגמה:

    {
  "director": "Frank Darabont",
  "genre": "Drama",
  "title": "The Shawshank Redemption",
  "year": 1994
}
  • ‫VECTORS_FILE: הנתיב המקומי לקובץ JSON שמכיל את החלק של הווקטורים באובייקט הנתונים.

    תוכן קובץ לדוגמה:

    {
  "genre_embedding": {
    "dense": {
      "values": [ 0.38638010860523064, 0.739343471733759, 0.16189056837017107, 0.5271366865924485 ]
    }
  },
  "plot_embedding": {
    "dense": {
      "values": [ 0.4752082440607731, 0.09026746166854707, 0.8752307753619009 ]
    }
  },
  "soundtrack_embedding": {
    "dense": {
      "values": [ 0.5920451749052875, 0.08301644173787519, 0.1264733498775969, 0.6196429624200321, 0.4925828581737443 ]
    }
  },
  "sparse_embedding": {
    "sparse": {
      "indices": [ 4065, 13326, 17377, 25918, 28105, 32683, 42998 ],
      "values": [ 1, 6, 3, 2, 8, 5, 2 ]
    }
  }
}
  • ‫DATA_OBJECT_ID: המזהה של אובייקט הנתונים.
  • ‫COLLECTION_ID: המזהה של האוסף.
  • ‫LOCATION: האזור שבו משתמשים ב-Agent Platform.
  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .

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

‫Linux,‏ macOS או Cloud Shell

gcloud vector-search collections data-objects create DATA_OBJECT_ID \
  --data=DATA_FILE \
  --vectors=VECTORS_FILE \
  --collection=COLLECTION_ID \
  --location=LOCATION \
  --project=PROJECT_ID

‏Windows (PowerShell)

gcloud vector-search collections data-objects create DATA_OBJECT_ID `
  --data=DATA_FILE `
  --vectors=VECTORS_FILE `
  --collection=COLLECTION_ID `
  --location=LOCATION `
  --project=PROJECT_ID

Windows‏ (cmd.exe)

gcloud vector-search collections data-objects create DATA_OBJECT_ID ^
  --data=DATA_FILE ^
  --vectors=VECTORS_FILE ^
  --collection=COLLECTION_ID ^
  --location=LOCATION ^
  --project=PROJECT_ID

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

Created dataObject [DATA_OBJECT_ID].

Python

from google.cloud import vectorsearch_v1

# Create the client
data_object_service_client = vectorsearch_v1.DataObjectServiceClient()

# Initialize request
data_object = vectorsearch_v1.DataObject(
    data={
        "title": "The Shawshank Redemption",
        "genre": "Drama",
        "year": 1994,
        "director": "Frank Darabont",
    },
    vectors={
        "plot_embedding": {
            "dense": {"values": [0.1, 0.2, 0.3]}
        },
        "genre_embedding": {
            "dense": {"values": [0.4, 0.5, 0.6, 0.7]}
        },
        "soundtrack_embedding": {
            "dense": {"values": [0.8, 0.9, 1.0, 1.1, 1.2]}
        },
        "sparse_embedding": {
            "sparse": {"values": [1.0, 2.0], "indices": [10, 20]}
        },
    },
)
request = vectorsearch_v1.CreateDataObjectRequest(
    parent="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
    data_object_id="DATA_OBJECT_ID",
    data_object=data_object,
)

# Make the request
response = data_object_service_client.create_data_object(request=request)

# Handle the response
print(response)

שדות שמוטמעים אוטומטית לפי סכימת האוסף מאוכלסים באופן אוטומטי. אפשר גם להשתמש בהטמעות משלכם (BYOE) כדי להגדיר ערכים של שדות וקטוריים שלא מתמלאים אוטומטית.

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

כדי לבצע הטמעה יעילה של מספר קטן של רשומות (עד 1,000 אובייקטים של נתונים לכל בקשה) בכמות גדולה, משתמשים ב-batchCreate. כל האצווה היא אטומית: או שכל אובייקטי הנתונים נוצרים, או שכל הבקשה נכשלת. למערכי נתונים גדולים יותר, מומלץ לייבא אובייקטים של נתונים מ-Cloud Storage.

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:batchCreate

תוכן בקשת JSON: 

{
  "requests": [
    {
      "parent": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
      "dataObjectId": "movie-1",
      "dataObject": {
        "data": {
          "title": "The Shawshank Redemption",
          "year": 1994
        },
        "vectors": {
          "plot_embedding": {
            "dense": { "values": [0.47, 0.09, 0.87] }
          }
        }
      }
    },
    {
      "parent": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
      "dataObjectId": "movie-2",
      "dataObject": {
        "data": {
          "title": "The Godfather",
          "year": 1972
        },
        "vectors": {
          "plot_embedding": {
            "dense": { "values": [0.12, 0.55, 0.31] }
          }
        }
      }
    }
  ]
}

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

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

{
  "dataObjects": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-1",
      "data": {
        "title": "The Shawshank Redemption",
        "year": 1994
      },
      "vectors": {
        "plot_embedding": {
          "dense": { "values": [0.47, 0.09, 0.87] }
        }
      }
    },
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-2",
      "data": {
        "title": "The Godfather",
        "year": 1972
      },
      "vectors": {
        "plot_embedding": {
          "dense": { "values": [0.12, 0.55, 0.31] }
        }
      }
    }
  ]
}

gcloud

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

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

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

‫Linux,‏ macOS או Cloud Shell

gcloud vector-search collections data-objects batch-create \
  --collection=COLLECTION_ID \
  --location=LOCATION \
  --project=PROJECT_ID \
  --requests='[
    {
      "parent":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
      "dataObjectId":"movie-1",
      "dataObject":{"data":{"title":"The Shawshank Redemption","year":1994},"vectors":{"plot_embedding":{"dense":{"values":[0.47,0.09,0.87]}}}}
    },
    {
      "parent":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
      "dataObjectId":"movie-2",
      "dataObject":{"data":{"title":"The Godfather","year":1972},"vectors":{"plot_embedding":{"dense":{"values":[0.12,0.55,0.31]}}}}
    }
  ]'

‏Windows (PowerShell)

gcloud vector-search collections data-objects batch-create `
  --collection=COLLECTION_ID `
  --location=LOCATION `
  --project=PROJECT_ID `
  --requests='[
    {
      "parent":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
      "dataObjectId":"movie-1",
      "dataObject":{"data":{"title":"The Shawshank Redemption","year":1994},"vectors":{"plot_embedding":{"dense":{"values":[0.47,0.09,0.87]}}}}
    },
    {
      "parent":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
      "dataObjectId":"movie-2",
      "dataObject":{"data":{"title":"The Godfather","year":1972},"vectors":{"plot_embedding":{"dense":{"values":[0.12,0.55,0.31]}}}}
    }
  ]'

‏Windows ‏(cmd.exe)

gcloud vector-search collections data-objects batch-create ^
  --collection=COLLECTION_ID ^
  --location=LOCATION ^
  --project=PROJECT_ID ^
  --requests='[
    {
      "parent":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
      "dataObjectId":"movie-1",
      "dataObject":{"data":{"title":"The Shawshank Redemption","year":1994},"vectors":{"plot_embedding":{"dense":{"values":[0.47,0.09,0.87]}}}}
    },
    {
      "parent":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
      "dataObjectId":"movie-2",
      "dataObject":{"data":{"title":"The Godfather","year":1972},"vectors":{"plot_embedding":{"dense":{"values":[0.12,0.55,0.31]}}}}
    }
  ]'

Python

from google.cloud import vectorsearch_v1

# Create the client
data_object_service_client = vectorsearch_v1.DataObjectServiceClient()

parent = "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID"

# Build per-DataObject create requests.
requests = [
    vectorsearch_v1.CreateDataObjectRequest(
        parent=parent,
        data_object_id="movie-1",
        data_object=vectorsearch_v1.DataObject(
            data={"title": "The Shawshank Redemption", "year": 1994},
            vectors={
                "plot_embedding": {"dense": {"values": [0.47, 0.09, 0.87]}},
            },
        ),
    ),
    vectorsearch_v1.CreateDataObjectRequest(
        parent=parent,
        data_object_id="movie-2",
        data_object=vectorsearch_v1.DataObject(
            data={"title": "The Godfather", "year": 1972},
            vectors={
                "plot_embedding": {"dense": {"values": [0.12, 0.55, 0.31]}},
            },
        ),
    ),
]

request = vectorsearch_v1.BatchCreateDataObjectsRequest(
    parent=parent,
    requests=requests,
)

# Make the request
response = data_object_service_client.batch_create_data_objects(request=request)

# Handle the response
for data_object in response.data_objects:
    print(data_object.name)

אחזור אובייקט נתונים

בדוגמה הבאה מוצג איך מקבלים אובייקט נתונים עם המזהה DATA_OBJECT_ID מאוסף עם המזהה COLLECTION_ID.

REST

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

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

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

GET https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/DATA_OBJECT_ID

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

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

{
  "name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/DATA_OBJECT_ID",
  "createTime": "2026-01-31T20:05:06Z",
  "updateTime": "2026-01-31T20:05:06Z",
  "data": {
    "title": "The Shawshank Redemption",
    "director": "Frank Darabont",
    "year": 1994,
    "genre": "Drama"
  },
  "vectors": {
    "sparse_embedding": {
      "sparse": {
        "values": [
          1,
          6,
          3,
          2,
          8,
          5,
          2
        ],
        "indices": [
          4065,
          13326,
          17377,
          25918,
          28105,
          32683,
          42998
        ]
      }
    },
    "genre_embedding": {
      "dense": {
        "values": [
          0.3863801,
          0.73934346,
          0.16189057,
          0.5271367
        ]
      }
    },
    "plot_embedding": {
      "dense": {
        "values": [
          0.47520825,
          0.090267465,
          0.8752308
        ]
      }
    },
    "soundtrack_embedding": {
      "dense": {
        "values": [
          0.5920452,
          0.08301644,
          0.12647335,
          0.619643,
          0.49258286
        ]
      }
    }
  }
}

gcloud

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

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

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

‫Linux,‏ macOS או Cloud Shell

gcloud vector-search collections data-objects describe DATA_OBJECT_ID \
  --collection=COLLECTION_ID \
  --location=LOCATION \
  --project=PROJECT_ID

‏Windows (PowerShell)

gcloud vector-search collections data-objects describe DATA_OBJECT_ID `
  --collection=COLLECTION_ID `
  --location=LOCATION `
  --project=PROJECT_ID

Windows‏ (cmd.exe)

gcloud vector-search collections data-objects describe DATA_OBJECT_ID ^
  --collection=COLLECTION_ID ^
  --location=LOCATION ^
  --project=PROJECT_ID

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

name: projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/DATA_OBJECT_ID
data:
  director: Frank Darabont
  genre: Drama
  title: The Shawshank Redemption
  year: 1994
vectors:
  genre_embedding:
    dense:
      values:
      - 0.3863801
      - 0.73934346
      - 0.16189057
      - 0.5271367
  plot_embedding:
    dense:
      values:
      - 0.47520825
      - 0.090267465
      - 0.8752308
  soundtrack_embedding:
    dense:
      values:
      - 0.5920452
      - 0.08301644
      - 0.12647335
      - 0.619643
      - 0.49258286
  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

Python

from google.cloud import vectorsearch_v1

# Create the client
data_object_service_client = vectorsearch_v1.DataObjectServiceClient()

# Initialize request
request = vectorsearch_v1.GetDataObjectRequest(
    name="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/DATA_OBJECT_ID",
)

# Make the request
response = data_object_service_client.get_data_object(request=request)

# Handle the response
print(response)

עדכון אובייקט נתונים

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

REST

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

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

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

PATCH https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/DATA_OBJECT_ID

תוכן בקשת JSON: 

{
  "data": {
    "title": "The Shawshank Redemption (updated)"
  },
  "vectors": {
    "plot_embedding": {
      "dense": {
        "values": [
          1.0,
          1.0,
          1.0
        ]
      }
    }
  }
}

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

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

{
  "name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/DATA_OBJECT_ID",
  "data": {
    "title": "The Shawshank Redemption (updated)"
  },
  "vectors": {
    "plot_embedding": {
      "dense": {
        "values": [
          1,
          1,
          1
        ]
      }
    }
  }
}

gcloud

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

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

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

‫Linux,‏ macOS או Cloud Shell

gcloud vector-search collections data-objects update DATA_OBJECT_ID \
  --collection=COLLECTION_ID \
  --location=LOCATION \
  --project=PROJECT_ID \
  --data='{"title": "The Shawshank Redemption (updated)"}' \
  --update-vectors='{"plot_embedding": {"dense": {"values": [1.0, 1.0, 1.0]}}}'

‏Windows (PowerShell)

gcloud vector-search collections data-objects update DATA_OBJECT_ID `
  --collection=COLLECTION_ID `
  --location=LOCATION `
  --project=PROJECT_ID `
  --data='{"title": "The Shawshank Redemption (updated)"}' `
  --update-vectors='{"plot_embedding": {"dense": {"values": [1.0, 1.0, 1.0]}}}'

‏Windows ‏(cmd.exe)

gcloud vector-search collections data-objects update DATA_OBJECT_ID ^
  --collection=COLLECTION_ID ^
  --location=LOCATION ^
  --project=PROJECT_ID ^
  --data='{"title": "The Shawshank Redemption (updated)"}' ^
  --update-vectors='{"plot_embedding": {"dense": {"values": [1.0, 1.0, 1.0]}}}'

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

Updated dataObject [DATA_OBJECT_ID].

Python

from google.cloud import vectorsearch_v1

# Create the client
data_object_service_client = vectorsearch_v1.DataObjectServiceClient()

# Initialize request
data_object = vectorsearch_v1.DataObject(
    name="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/DATA_OBJECT_ID",
    data={"title": "The Shawshank Redemption (updated)"},
    vectors={
        "plot_embedding": {
            "dense": {"values": [1., 1., 1.]}
        },
    },
)
request = vectorsearch_v1.UpdateDataObjectRequest(
    data_object=data_object,
)

# Make the request
response = data_object_service_client.update_data_object(request=request)

# Handle the response
print(response)

חבילת עדכונים של אובייקטים של נתונים

כדי לעדכן הרבה אובייקטים של נתונים בבת אחת, משתמשים ב-batchUpdate. אפשר לעדכן עד 1,000 אובייקטים של נתונים באצווה אחת. כל בקשה לכל רשומה מציינת את dataObject (שחייב לכלול את המשאב המלא שלו name בתוספת השדות שרוצים לשנות) ואת updateMask שבו מפורטים השדות שרוצים להחליף. השדות שלא מופיעים במסכה לא משתנים.

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:batchUpdate

תוכן בקשת JSON: 

{
  "requests": [
    {
      "dataObject": {
        "name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-1",
        "data": { "genre": "Thriller" }
      },
      "updateMask": "data.genre"
    },
    {
      "dataObject": {
        "name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-2",
        "vectors": {
          "plot_embedding": {
            "dense": { "values": [0.21, 0.34, 0.55] }
          }
        }
      },
      "updateMask": "vectors.plot_embedding"
    }
  ]
}

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

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

{}

gcloud

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

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

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

‫Linux,‏ macOS או Cloud Shell

gcloud vector-search collections data-objects batch-update \
  --collection=COLLECTION_ID \
  --location=LOCATION \
  --project=PROJECT_ID \
  --requests='[
    {
      "dataObject":{"name":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-1","data":{"genre":"Thriller"}},
      "updateMask":"data.genre"
    },
    {
      "dataObject":{"name":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-2","vectors":{"plot_embedding":{"dense":{"values":[0.21,0.34,0.55]}}}},
      "updateMask":"vectors.plot_embedding"
    }
  ]'

‏Windows (PowerShell)

gcloud vector-search collections data-objects batch-update `
  --collection=COLLECTION_ID `
  --location=LOCATION `
  --project=PROJECT_ID `
  --requests='[
    {
      "dataObject":{"name":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-1","data":{"genre":"Thriller"}},
      "updateMask":"data.genre"
    },
    {
      "dataObject":{"name":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-2","vectors":{"plot_embedding":{"dense":{"values":[0.21,0.34,0.55]}}}},
      "updateMask":"vectors.plot_embedding"
    }
  ]'

‏Windows ‏(cmd.exe)

gcloud vector-search collections data-objects batch-update ^
  --collection=COLLECTION_ID ^
  --location=LOCATION ^
  --project=PROJECT_ID ^
  --requests='[
    {
      "dataObject":{"name":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-1","data":{"genre":"Thriller"}},
      "updateMask":"data.genre"
    },
    {
      "dataObject":{"name":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-2","vectors":{"plot_embedding":{"dense":{"values":[0.21,0.34,0.55]}}}},
      "updateMask":"vectors.plot_embedding"
    }
  ]'

Python

from google.cloud import vectorsearch_v1
from google.protobuf import field_mask_pb2

# Create the client
data_object_service_client = vectorsearch_v1.DataObjectServiceClient()

parent = "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID"

# Each entry specifies the DataObject to update (with its full resource
# name) and an update_mask listing the fields to overwrite. Fields not
# listed in the mask are left unchanged.
requests = [
    vectorsearch_v1.UpdateDataObjectRequest(
        data_object=vectorsearch_v1.DataObject(
            name=f"{parent}/dataObjects/movie-1",
            data={"genre": "Thriller"},
        ),
        update_mask=field_mask_pb2.FieldMask(paths=["data.genre"]),
    ),
    vectorsearch_v1.UpdateDataObjectRequest(
        data_object=vectorsearch_v1.DataObject(
            name=f"{parent}/dataObjects/movie-2",
            vectors={
                "plot_embedding": {"dense": {"values": [0.21, 0.34, 0.55]}},
            },
        ),
        update_mask=field_mask_pb2.FieldMask(paths=["vectors.plot_embedding"]),
    ),
]

request = vectorsearch_v1.BatchUpdateDataObjectsRequest(
    parent=parent,
    requests=requests,
)

# Make the request
data_object_service_client.batch_update_data_objects(request=request)

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

בדוגמה הבאה מוצג איך לייבא אובייקטים של נתונים מ-Cloud Storage לאוסף עם המזהה COLLECTION_ID. כדאי להשתמש בייבוא למערכי נתונים גדולים. לייבוא בכמות גדולה של נתונים קטנים יותר (עד 1,000 רשומות), כדאי ליצור אובייקטים של נתונים באצווה.

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:importDataObjects

תוכן בקשת JSON: 

{
  "gcsImport": {
    "contentsUri": "gs://your-bucket/path/to/your-data.json",
    "errorUri": "gs://your-bucket/path/to/import-errors/",
    "outputUri": "gs://your-bucket/path/to/import-output/"
  }
}

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

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

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/operation-1770039043815-649d75471f76e-08de3049-276a02be",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.vectorsearch.v1.ImportDataObjectsMetadata",
    "createTime": "2026-02-02T13:30:43.874527852Z"
  },
  "done": false
}

gcloud

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

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

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

‫Linux,‏ macOS או Cloud Shell

gcloud vector-search collections import-data-objects COLLECTION_ID \
  --location=LOCATION \
  --project=PROJECT_ID \
  --gcs-import-contents-uri="gs://your-bucket/path/to/your-data.json" \
  --gcs-import-error-uri="gs://your-bucket/path/to/import-errors/" \
  --gcs-import-output-uri="gs://your-bucket/path/to/import-output/" \
  --async

‏Windows (PowerShell)

gcloud vector-search collections import-data-objects COLLECTION_ID `
  --location=LOCATION `
  --project=PROJECT_ID `
  --gcs-import-contents-uri="gs://your-bucket/path/to/your-data.json" `
  --gcs-import-error-uri="gs://your-bucket/path/to/import-errors/" `
  --gcs-import-output-uri="gs://your-bucket/path/to/import-output/" `
  --async

Windows‏ (cmd.exe)

gcloud vector-search collections import-data-objects COLLECTION_ID ^
  --location=LOCATION ^
  --project=PROJECT_ID ^
  --gcs-import-contents-uri="gs://your-bucket/path/to/your-data.json" ^
  --gcs-import-error-uri="gs://your-bucket/path/to/import-errors/" ^
  --gcs-import-output-uri="gs://your-bucket/path/to/import-output/" ^
  --async

Python

from google.cloud import vectorsearch_v1

# Create the client
vector_search_service_client = vectorsearch_v1.VectorSearchServiceClient()

# Initialize request
request = vectorsearch_v1.ImportDataObjectsRequest(
    name="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
    gcs_import={
      "contents_uri": "gs://your-bucket/path/to/your-data/",
      "error_uri": "gs://your-bucket/path/to/import-errors/",
    },
)

# Make the request
operation = vector_search_service_client.import_data_objects(request=request)

# Wait for the result (note this may take up to several minutes)
operation.result()

התיקייה gs://your-bucket/path/to/your-data/ יכולה להכיל קובץ אחד או יותר, וכל קובץ יכול להכיל כמה אובייקטים של נתונים. אפשר להשתמש במבנה הזה למערכי נתונים גדולים שמופיעים בכמה קבצים. הפורמטים הבאים של קבצים נתמכים באחזור מידע על ידי סוכן:

  • ‫JSONL, שבו כל שורה היא אובייקט JSON עם שלושה מאפיינים ברמה העליונה: id,‏ data ו-vectors. כדאי להשתמש בפורמט הזה כשרוצים להזין נתונים קריאים לאנשים כדי לבדוק ולערוך אותם באופן ידני במערכי נתונים חדשים של שליפת מידע על סוכנים.
  • ‫AVRO: משתמשים בפורמט הזה לערכות נתונים חדשות של שליפת נתונים מסוכנים כשצריך פורמט בינארי קומפקטי שעבר אימות סכמה – בדרך כלל לערכות נתונים גדולות שנוצרות על ידי כלים של צינורות עיבוד נתונים כמו Dataflow,‏ Beam או Spark.
  • ‫JSON של חיפוש וקטורי: משתמשים בפורמט הזה רק כשמעבירים מערך נתונים קיים בפורמט JSON של חיפוש וקטורי (חיפוש וקטורי 1.0) ורוצים לעשות בו שימוש חוזר כמו שהוא.
  • ‫Vector Search AVRO: השתמשו בפורמט הזה רק כשאתם מעבירים מערך נתונים קיים של Vector Search (גרסה 1.0) בפורמט AVRO ורוצים לעשות בו שימוש חוזר כמו שהוא.

JSONL

בדוגמה הבאה מוצג פורמט JSONL עם המאפיינים הנדרשים. כל שורה בקובץ הקלט היא אובייקט נתונים יחיד עם המאפיינים ברמה העליונה id,‏ data ו-vectors.

{
  "id": "movie-789",
  "data": {
    "title":"The Shawshank Redemption",
    "plot": "...",
    "year":1994,
    "avg_rating": 8.5,
    "movie_runtime_info": {
        "hours": 2,
        "minutes": 5
    },
  },
  "vectors": {
    "title_embedding": [-0.23, 0.88, 0.11, ...],
    "sparse_embedding": {
      "values": [0.01, -0.93, 0.27, ...],
      "indices": [23, 83, 131, ...]
    }
  }
}

AVRO

בקבצי AVRO, כל רשומה צריכה להיות תואמת לסכימת ה-Avro שמוצגת ב-DataObject. השדות משקפים את פורמט JSONL:

  • id (חובה string).
  • ‫vectors (map, ברירת מחדל {}). כל רשומה מוגדרת באמצעות שם הווקטור, והערך שלה הוא array של float (ווקטור צפוף) או רשומה של SparseVector עם values (מערך של float) ו-indices (מערך של long).
  • ‫data (ניתן להגדרה כ-nullable‏ map, ברירת המחדל היא null). המפתחות הם שמות של שדות נתונים. כל ערך הוא רשומה DataValue שהשדה value שלה הוא איחוד של סוגי הנתונים הפרימיטיביים הנתמכים (boolean, ‏ int, ‏ long, ‏ float, ‏ double,‏ string) בתוספת array של DataValue ו-map של string עד DataValue למבנים מקוננים.
  • ‫etag (nullable string, ברירת מחדל null).
{
  "namespace": "com.google.cloud.ai.vectorsearch",
  "type": "record",
  "name": "DataObject",
  "fields": [
    {
      "name": "id",
      "type": "string"
    },
    {
      "name": "vectors",
      "type": {
        "type": "map",
        "values": [
          {
            "type": "array",
            "items": "float"
          },
          {
            "type": "record",
            "name": "SparseVector",
            "fields": [
              {
                "name": "values",
                "type": { "type": "array", "items": "float" }
              },
              {
                "name": "indices",
                "type": { "type": "array", "items": "long" }
              }
            ]
          }
        ]
      },
      "default": {}
    },
    {
      "name": "data",
      "type": [
        "null",
        {
          "type": "map",
          "values": {
            "type": "record",
            "name": "DataValue",
            "fields": [
              {
                "name": "value",
                "type": [
                  "boolean",
                  "int",
                  "long",
                  "float",
                  "double",
                  "string",
                  {
                    "type": "array",
                    "items": "DataValue"
                  },
                  {
                    "type": "map",
                    "values": "DataValue"
                  }
                ]
              }
            ]
          }
        }
      ],
      "default": null
    },
    {
      "name": "etag",
      "type": [
        "null",
        "string"
      ],
      "default": null
    }
  ]
}

בקטע הקוד הבא מוצג התוכן הרעיוני של רשומה יחידה בפורמט AVRO שתואמת לדוגמה הקודמת בפורמט JSONL. שימו לב שבסכימה הזו כל רשומה ב-data עטופה ברשומה DataValue (עם שדה value יחיד), וכך AVRO מייצג את הסוגים ההטרוגניים ב-data:

{
  "id": "movie-789",
  "vectors": {
    "title_embedding": [-0.23, 0.88, 0.11],
    "sparse_embedding": {
      "values": [0.01, -0.93, 0.27],
      "indices": [23, 83, 131]
    }
  },
  "data": {
    "title": { "value": "The Shawshank Redemption" },
    "plot": { "value": "..." },
    "year": { "value": 1994 },
    "avg_rating": { "value": 8.5 },
    "movie_runtime_info": {
      "value": {
        "hours":   { "value": 2 },
        "minutes": { "value": 5 }
      }
    }
  }
}

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

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

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:exportDataObjects

תוכן בקשת JSON: 

{
  "gcsDestination": {
    "exportUri": "gs://your-bucket/path/to/export-dir/",
    "format": "JSONL"
  }
}

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

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

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/operation-1770039043815-649d75471f76e-08de3049-276a02be",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.vectorsearch.v1.ExportDataObjectsMetadata",
    "createTime": "2026-02-02T13:30:43.874527852Z"
  },
  "done": false
}

gcloud

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

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

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

‫Linux,‏ macOS או Cloud Shell

gcloud vector-search collections export-data-objects COLLECTION_ID \
  --location=LOCATION \
  --project=PROJECT_ID \
  --gcs-destination-export-uri="gs://your-bucket/path/to/export-dir/" \
  --gcs-destination-format="jsonl" \
  --async

‏Windows (PowerShell)

gcloud vector-search collections export-data-objects COLLECTION_ID `
  --location=LOCATION `
  --project=PROJECT_ID `
  --gcs-destination-export-uri="gs://your-bucket/path/to/export-dir/" `
  --gcs-destination-format="jsonl" `
  --async

Windows‏ (cmd.exe)

gcloud vector-search collections export-data-objects COLLECTION_ID ^
  --location=LOCATION ^
  --project=PROJECT_ID ^
  --gcs-destination-export-uri="gs://your-bucket/path/to/export-dir/" ^
  --gcs-destination-format="jsonl" ^
  --async

Python

from google.cloud import vectorsearch_v1

# Create the client
vector_search_service_client = vectorsearch_v1.VectorSearchServiceClient()

# Initialize request
request = vectorsearch_v1.ExportDataObjectsRequest(
    name="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
    gcs_destination={
        "export_uri": "gs://your-bucket/path/to/export-dir/",
        "format": vectorsearch_v1.ExportDataObjectsRequest.GcsExportDestination.Format.JSONL,
    },
)

# Make the request
operation = vector_search_service_client.export_data_objects(request=request)

# Wait for the result (note this may take up to several minutes)
operation.result()

מחיקת אובייקט נתונים

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

REST

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

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

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

DELETE https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/DATA_OBJECT_ID

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

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

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/operation-1770039043815-649d75471f76e-08de3049-276a02be",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.vectorsearch.v1.ExportDataObjectsMetadata",
    "createTime": "2026-02-02T13:30:43.874527852Z"
  },
  "done": false
}

gcloud

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

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

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

‫Linux,‏ macOS או Cloud Shell

gcloud vector-search collections data-objects delete DATA_OBJECT_ID \
  --collection=COLLECTION_ID \
  --location=LOCATION \
  --project=PROJECT_ID

‏Windows (PowerShell)

gcloud vector-search collections data-objects delete DATA_OBJECT_ID `
  --collection=COLLECTION_ID `
  --location=LOCATION `
  --project=PROJECT_ID

Windows‏ (cmd.exe)

gcloud vector-search collections data-objects delete DATA_OBJECT_ID ^
  --collection=COLLECTION_ID ^
  --location=LOCATION ^
  --project=PROJECT_ID

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

Deleted dataObject [DATA_OBJECT_ID].

Python

from google.cloud import vectorsearch_v1

# Create the client
data_object_service_client = vectorsearch_v1.DataObjectServiceClient()

# Initialize request
request = vectorsearch_v1.DeleteDataObjectRequest(
    name="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/DATA_OBJECT_ID",
)

# Make the request
data_object_service_client.delete_data_object(request=request)

מחיקה של אובייקטים של נתונים בכמות גדולה

כדי למחוק הרבה אובייקטים של נתונים בבת אחת, משתמשים ב-batchDelete עם רשימה של שמות משאבים מלאים של אובייקטים של נתונים. אפשר למחוק עד 1,000 אובייקטי נתונים באצווה אחת.

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:batchDelete

תוכן בקשת JSON: 

{
  "requests": [
    { "name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-1" },
    { "name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-2" }
  ]
}

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

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

{}

gcloud

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

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

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

‫Linux,‏ macOS או Cloud Shell

gcloud vector-search collections data-objects batch-delete \
  --collection=COLLECTION_ID \
  --location=LOCATION \
  --project=PROJECT_ID \
  --requests='[
    {"name":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-1"},
    {"name":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-2"}
  ]'

‏Windows (PowerShell)

gcloud vector-search collections data-objects batch-delete `
  --collection=COLLECTION_ID `
  --location=LOCATION `
  --project=PROJECT_ID `
  --requests='[
    {"name":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-1"},
    {"name":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-2"}
  ]'

‏Windows ‏(cmd.exe)

gcloud vector-search collections data-objects batch-delete ^
  --collection=COLLECTION_ID ^
  --location=LOCATION ^
  --project=PROJECT_ID ^
  --requests='[
    {"name":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-1"},
    {"name":"projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/movie-2"}
  ]'

Python

from google.cloud import vectorsearch_v1

# Create the client
data_object_service_client = vectorsearch_v1.DataObjectServiceClient()

parent = "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID"

requests = [
    vectorsearch_v1.DeleteDataObjectRequest(
        name=f"{parent}/dataObjects/movie-1",
    ),
    vectorsearch_v1.DeleteDataObjectRequest(
        name=f"{parent}/dataObjects/movie-2",
    ),
]

request = vectorsearch_v1.BatchDeleteDataObjectsRequest(
    parent=parent,
    requests=requests,
)

# Make the request
data_object_service_client.batch_delete_data_objects(request=request)

ספירת אובייקטים של נתונים

כדי לספור כמה אובייקטים של נתונים מכיל אוסף, משתמשים בפעולה aggregate עם שיטת הצבירה COUNT. אותה קריאה מקבלת ביטוי סינון אופציונלי בפורמט JSON, כדי שתוכלו לספור רק את אובייקטי הנתונים שתואמים לתנאי (לדוגמה, genre == "sci-fi").

כדי לספור כל אובייקט נתונים באוסף, משמיטים את המסנן.

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",
  "filter": { "genre": { "$eq": "sci-fi" } }
}

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

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

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

gcloud

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

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

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

‫Linux,‏ macOS או Cloud Shell

gcloud vector-search collections data-objects aggregate \
  --collection=COLLECTION_ID \
  --location=LOCATION \
  --project=PROJECT_ID \
  --aggregation-method=count \
  --json-filter='{"genre": {"$eq": "sci-fi"}}'

‏Windows (PowerShell)

gcloud vector-search collections data-objects aggregate `
  --collection=COLLECTION_ID `
  --location=LOCATION `
  --project=PROJECT_ID `
  --aggregation-method=count `
  --json-filter='{"genre": {"$eq": "sci-fi"}}'

‏Windows ‏(cmd.exe)

gcloud vector-search collections data-objects aggregate ^
  --collection=COLLECTION_ID ^
  --location=LOCATION ^
  --project=PROJECT_ID ^
  --aggregation-method=count ^
  --json-filter='{"genre": {"$eq": "sci-fi"}}'

Python

from google.cloud import vectorsearch_v1
from google.protobuf import struct_pb2
from google.protobuf import json_format

# Create the client
search_client = vectorsearch_v1.DataObjectSearchServiceClient()

parent = "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID"

# Optional: build a JSON filter. Omit `filter=` to count everything.
filter_struct = json_format.ParseDict(
    {"genre": {"$eq": "sci-fi"}}, struct_pb2.Struct()
)

request = vectorsearch_v1.AggregateDataObjectsRequest(
    parent=parent,
    aggregate=vectorsearch_v1.AggregationMethod.COUNT,
    filter=filter_struct,
)

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

# The count value is returned in aggregate_results[0].
for result in response.aggregate_results:
    print(result)

מה השלב הבא?