Gunakan operasi ListVectors untuk mencantumkan data vektor dari indeks vektor - Object Storage Service - Alibaba Cloud - Object Storage Service

Operasi ListVectors menampilkan semua data vektor dalam indeks vektor.

Permissions

Secara default, Akun Alibaba Cloud memiliki izin penuh untuk mengakses semua sumber daya. Pengguna RAM dan Peran RAM tidak memiliki izin apa pun secara default. Pemilik Akun Alibaba Cloud atau administrator harus memberikan izin kepada mereka melalui RAM policy atau bucket policy.

API	Action	Description
ListVectors	`oss:ListVectors`	Menampilkan data vektor.

Sintaks permintaan

POST /?listVectors HTTP/1.1
Host: examplebucket-123***456.cn-hangzhou-internal.oss-vectors.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue
Content-type: application/json

{
   "indexName": "string",
   "maxResults": int,
   "nextToken": "string",
   "returnData": boolean,
   "returnMetadata": boolean,
   "segmentCount": int,
   "segmentIndex": int,
   "filter": {
       "$and": [{
           "type": {
               "$in": ["comedy", "documentary"]
           }
       }, {
           "year": {
               "$eq": "2020"
           }
       }]
    }
}

Request headers

Operasi ini hanya menggunakan header permintaan umum. Untuk informasi selengkapnya, lihat Common HTTP headers.

Parameter permintaan

Parameter	Type	Required	Example	Description
indexName	String	Yes	vectorindex1	Nama indeks vektor.
maxResults	Integer	No	500	Jumlah maksimum hasil yang dikembalikan per permintaan. Nilai default: 500. Nilai maksimum: 1.000.
nextToken	String	No	CAESCG15aC-xxxxx	Token kueri. Tetapkan parameter ini ke nilai `nextToken` dari respons sebelumnya untuk mengambil halaman hasil berikutnya. Untuk permintaan pertama, jangan tentukan parameter ini. Panjang token dapat berkisar antara 1 hingga 2.048 byte.
returnData	Boolean	No	false	Menentukan apakah data vektor akan dikembalikan. Nilai yang valid: true false (default)
returnMetadata	Boolean	No	false	Menentukan apakah metadata akan dikembalikan. Nilai yang valid: true false (default)
segmentCount	Integer	No	1	Menentukan tingkat paralelisme untuk operasi `ListVectors` paralel. Nilainya dapat mencapai 16. Untuk eksekusi serial, tetapkan parameter ini ke 1.
segmentIndex	Integer	No	0	Saat menjalankan operasi `ListVectors` paralel, nilai `segmentIndex` harus lebih kecil dari nilai `segmentCount`.
filter	Container	No	N/A	Memfilter hasil kueri berdasarkan metadata. Batasan berikut berlaku: Ukuran total metadata dalam ekspresi filter tidak boleh melebihi 20 KB. Jumlah item metadata dalam ekspresi filter tidak boleh melebihi 1.024. Kondisi filter dapat disarangkan hingga kedalaman 8 level. `filter` hanya didukung untuk indeks mode Standard. Indeks mode Fusion tidak mendukung parameter kueri `filter` secara default.

Operator filter

Operator	Supported type	Description
`$eq`	String	Mencocokkan nilai eksak. Saat digunakan dengan metadata bertipe array, operator ini mengembalikan `true` jika nilai input cocok dengan salah satu elemen dalam array.
`$ne`	String	Tidak sama dengan.
`$gt`	Number	Lebih besar dari.
`$gte`	Number	Lebih besar dari atau sama dengan.
`$lt`	Number	Lebih kecil dari.
`$lte`	Number	Lebih kecil dari atau sama dengan.
`$in`	Array of strings	Mencocokkan nilai apa pun dalam array (mirip dengan operasi SQL `IN`)
`$nin`	Array of strings	Tidak mencocokkan nilai apa pun dalam array (mirip dengan operasi SQL `NOT IN`)
`$exists`	Boolean	Memeriksa apakah kunci metadata ada.
`$and`	Array of filter objects	Menjalankan operasi logika AND pada array yang terdiri dari dua atau lebih ekspresi filter.
`$or`	Array of filter objects	Menjalankan operasi logika OR pada array yang terdiri dari dua atau lebih ekspresi filter.
`$nor`	Array of filter objects	Menjalankan operasi logika NOR pada array yang terdiri dari dua atau lebih ekspresi filter.

Response headers

Operasi ini hanya menggunakan header respons umum. Untuk informasi selengkapnya, lihat Common HTTP headers.

Elemen respons

Parameter	Type	Example	Description
nextToken	String	CAESCG15aC2xxxxx	Token kueri untuk halaman hasil berikutnya. Jika elemen ini kosong, semua hasil telah dikembalikan.
vectors	Array of objects	N/A	Daftar objek vektor.
key	String	doc-001	Kunci primary dari vektor. Node induk: `vectors`
data	Object	N/A	Data vektor. Elemen ini hanya dikembalikan ketika `returnData` diatur ke `true`. Node induk: `vectors`
metadata	Object	N/A	Metadata vektor. Elemen ini hanya dikembalikan ketika `returnMetadata` diatur ke `true`. Node induk: `vectors`

Contoh

Mode Standard

Contoh permintaan

POST /?listVectors HTTP/1.1
Host: examplebucket-123***456.cn-hangzhou-internal.oss-vectors.aliyuncs.com
Date: Thu, 17 Apr 2025 01:33:47 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218
Content-type: application/json

{
   "indexName": "vectorindex1",
   "maxResults": 10,
   "returnData": true,
   "returnMetadata": true
}

Contoh respons

HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Thu, 17 Apr 2025 01:33:47 GMT
Connection: keep-alive
Server: AliyunOSS
Content-type: application/json

{
   "nextToken": "CAESCG15aC2xxxxx",
   "vectors": [ 
      { 
         "data": {
            "float32": [0.1, 0.2, 0.3, 0.4, 0.5]
         },
         "key": "doc-001",
         "metadata": {
             "category": ["technology", "ai"],
             "title": "Introduction to Vector Search"
         }
      },
      { 
         "data": {
            "float32": [0.2, 0.3, 0.4, 0.5, 0.6]
         },
         "key": "doc-002",
         "metadata": {
             "category": ["science"],
             "title": "Advanced Vector Operations"
         }
      }
   ]
}

Mode Fusion

Catatan

Untuk indeks mode Fusion, data menggunakan nama bidang vektor yang ditentukan dalam skema saat indeks dibuat, bukan nama bidang vektor tetap float32 yang digunakan dalam mode Standard, dan dapat mengembalikan beberapa bidang vektor.

Contoh permintaan

POST /?listVectors HTTP/1.1
Host: examplebucket-123***456.cn-hangzhou-internal.oss-vectors.aliyuncs.com
Date: Thu, 17 Apr 2025 01:33:47 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218
Content-type: application/json

{
   "indexName": "vectorindex1",
   "maxResults": 10,
   "returnData": true,
   "returnMetadata": true
}

Contoh respons

HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Thu, 17 Apr 2025 01:33:47 GMT
Connection: keep-alive
Server: AliyunOSS
Content-type: application/json

{
   "nextToken": "CAESCG15aC2xxxxx",
   "vectors": [ 
      { 
         "data": {
            "vector_field_name_1": [0.1, 0.2, 0.3, 0.4, 0.5]
         },
         "key": "doc-001",
         "metadata": {
             "category": ["technology", "ai"],
             "title": "Introduction to Vector Search"
         }
      },
      { 
         "data": {
            "vector_field_name_1": [0.1, 0.2, 0.3, 0.4, 0.5],
            "vector_field_name_2": [0.2, 0.3, 0.4, 0.5, 0.6]
         },
         "key": "doc-002",
         "metadata": {
             "category": ["science"],
             "title": "Advanced Vector Operations"
         }
      }
   ]
}

SDK

Operasi ListVectors tersedia dalam SDK berikut:

ossutil CLI

Untuk perintah ossutil yang sesuai, lihat list-vectors.

Kode error

Error code	HTTP status code	Description
VectorIndexParameterInvalid	400	Parameter indeks vektor yang diberikan dalam permintaan tidak valid.
MalformedJson	400	Badan permintaan berisi JSON yang tidak valid.
AccessDenied	403	Penyebab yang mungkin: Permintaan tidak menyertakan informasi otentikasi pengguna. Anda tidak memiliki izin yang diperlukan untuk operasi ini.
NoSuchVectorIndex	404	Indeks vektor yang ditentukan tidak ada.
QpsLimitExceeded	503	Laju permintaan melebihi batas QPS.