Mengkueri Koleksi untuk Objek Data

Tujuan Query API adalah untuk mengambil Objek Data dari Koleksi menggunakan filter. Hal ini mirip dengan membuat kueri tabel database dan menggunakan klausa WHERE SQL. Anda juga dapat menggunakan agregasi untuk mendapatkan jumlah Objek Data yang cocok dengan filter.

Bahasa ekspresi filter

Selain fungsi penelusuran KNN/ANN, Vector Search 2.0 menyediakan kemampuan kueri serbaguna menggunakan bahasa kueri kustom. Bahasa kueri dijelaskan dalam tabel berikut.

Filter	Deskripsi	Jenis yang Didukung	Contoh
$eq	Mencocokkan Objek Data dengan nilai kolom yang sama dengan nilai yang ditentukan.	Angka, string, boolean	{"genre": {"$eq": "documentary"}}
$ne	Mencocokkan Objek Data dengan nilai kolom yang tidak sama dengan nilai yang ditentukan.	Angka, string, boolean	{"genre": {"$ne": "drama"}}
$gt	Mencocokkan Objek Data dengan nilai kolom yang lebih besar dari nilai yang ditentukan.	Angka	{"year": {"$gt": 2019}}
$gte	Mencocokkan Objek Data dengan nilai kolom yang lebih besar dari atau sama dengan nilai yang ditentukan.	Angka	{"year": {"$gte": 2020}}
$lt	Mencocokkan Objek Data dengan nilai kolom yang kurang dari nilai yang ditentukan.	Angka	{"year": {"$lt": 2020}}
$lte	Mencocokkan Objek Data dengan nilai kolom yang kurang dari atau sama dengan nilai yang ditentukan.	Angka	{"year": {"$lte": 2020}}
$in	Mencocokkan Objek Data dengan nilai kolom yang ada di array tertentu.	String	{"genre": {"$in": ["comedy", "documentary"]}}
$nin	Mencocokkan Objek Data dengan nilai kolom yang tidak ada di array tertentu.	String	{"genre": {"$nin": ["comedy", "documentary"]}}
$and	Menggabungkan klausa kueri dengan AND logis.	-	{"$and": [{"genre": {"$eq": "drama"}}, {"year": {"$gte": 2020}}]}
$atau	Menggabungkan klausa kueri dengan OR logis.	-	{"$or": [{"genre": {"$eq": "drama"}}, {"year": {"$gte": 2020}}]}
$all	Memilih dokumen yang nilai array kolomnya berisi semua nilai yang ditentukan.	-	{"colors": {"$all": ["red", "blue"]}}

Catatan: Ekspresi filter tidak dapat bertingkat lebih dari dua tingkat.

Membuat Kueri Koleksi

Contoh berikut menunjukkan cara menggunakan filter untuk membuat kueri Objek Data dalam Kumpulan dengan ID COLLECTION_ID.

REST

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

• COLLECTION_ID: ID koleksi.
• LOCATION: Region tempat Anda menggunakan Platform Agen.
• PROJECT_ID: Project ID Anda. Google Cloud

Metode HTTP dan URL:

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

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

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

curl (Linux, macOS, atau Cloud Shell)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke gcloud CLI menggunakan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login, atau dengan menggunakan Cloud Shell, yang secara otomatis membuat Anda login ke gcloud CLI. Anda dapat memeriksa akun yang saat ini aktif dengan menjalankan gcloud auth list.

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut:

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

PowerShell (Windows)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke gcloud CLI menggunakan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login. Anda dapat memeriksa akun yang saat ini aktif dengan menjalankan gcloud auth list.

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut:

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

Anda akan melihat respons JSON seperti berikut:

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

Sebelum menggunakan salah satu data perintah di bawah, lakukan penggantian berikut:

• COLLECTION_ID: ID koleksi.
• LOCATION: Region tempat Anda menggunakan Platform Agen.
• PROJECT_ID: Project ID Anda. Google Cloud

Jalankan perintah berikut:

Linux, macOS, atau Cloud Shell

Catatan: Pastikan Anda telah menginisialisasi Google Cloud CLI dengan autentikasi dan sebuah project dengan menjalankan gcloud init; atau gcloud auth login dan gcloud config set project.

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

Catatan: Pastikan Anda telah menginisialisasi Google Cloud CLI dengan autentikasi dan sebuah project dengan menjalankan gcloud init; atau gcloud auth login dan gcloud config set project.

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

Catatan: Pastikan Anda telah menginisialisasi Google Cloud CLI dengan autentikasi dan sebuah project dengan menjalankan gcloud init; atau gcloud auth login dan gcloud config set project.

Catatan: Jika perintah ini menggunakan ' untuk mengutip konten, ganti tanda kutip tunggal dengan tanda kutip ganda. Jika kutipan bertingkat, gunakan \" untuk meng-escape tanda kutip dalam.

gcloud beta 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

Anda akan melihat respons seperti berikut:

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

# Create the client
data_object_search_service_client = vectorsearch_v1beta.DataObjectSearchServiceClient()

# Initialize request
request = vectorsearch_v1beta.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)

Untuk melakukan agregasi, Anda menggunakan endpoint aggregate dan menentukan jenis agregasi dalam isi permintaan.

Contoh berikut menunjukkan cara menghitung semua Objek Data dalam Koleksi dengan ID COLLECTION_ID.

REST

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

• COLLECTION_ID: ID koleksi.
• LOCATION: Region tempat Anda menggunakan Platform Agen.
• PROJECT_ID: Project ID Anda. Google Cloud

Metode HTTP dan URL:

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

Meminta isi JSON:

{
  "aggregate": "count"
}

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

curl (Linux, macOS, atau Cloud Shell)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke gcloud CLI menggunakan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login, atau dengan menggunakan Cloud Shell, yang secara otomatis membuat Anda login ke gcloud CLI. Anda dapat memeriksa akun yang saat ini aktif dengan menjalankan gcloud auth list.

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut:

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

PowerShell (Windows)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke gcloud CLI menggunakan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login. Anda dapat memeriksa akun yang saat ini aktif dengan menjalankan gcloud auth list.

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut:

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

Anda akan melihat respons JSON seperti berikut:

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

gcloud

Sebelum menggunakan salah satu data perintah di bawah, lakukan penggantian berikut:

• COLLECTION_ID: ID koleksi.
• LOCATION: Region tempat Anda menggunakan Platform Agen.
• PROJECT_ID: Project ID Anda. Google Cloud

Jalankan perintah berikut:

Linux, macOS, atau Cloud Shell

Catatan: Pastikan Anda telah menginisialisasi Google Cloud CLI dengan autentikasi dan sebuah project dengan menjalankan gcloud init; atau gcloud auth login dan gcloud config set project.

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

Windows (PowerShell)

Catatan: Pastikan Anda telah menginisialisasi Google Cloud CLI dengan autentikasi dan sebuah project dengan menjalankan gcloud init; atau gcloud auth login dan gcloud config set project.

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

Windows (cmd.exe)

Catatan: Pastikan Anda telah menginisialisasi Google Cloud CLI melalui autentikasi dan sebuah project dengan menjalankan gcloud init; atau gcloud auth login dan gcloud config set project.

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

Anda akan melihat respons seperti berikut:

aggregateResults:
- count: 1000

Python

from google.cloud import vectorsearch_v1beta

# Create the client
data_object_search_service_client = vectorsearch_v1beta.DataObjectSearchServiceClient()

# Initialize request
request = vectorsearch_v1beta.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)

Apa langkah selanjutnya?

• Pelajari cara menelusuri Objek Data.