標量檢索是OSS提供的基于Object元數據的索引功能，允許您自定義條件，快速篩選并獲取Object列表。可以幫助您更好地管理與了解數據結構，方便您后續查詢、統計和管理Object。
使用場景
數據審計場景
通過標量檢索，您可以快速定位文件，以滿足數據審計或監管需求。例如，在金融服務行業，您可以通過自定義標簽、訪問權限等元數據進行篩選，從而找到具有特定敏感性級別或特定權限的文件，以提升數據審計的效率。
企業備份與歸檔場景
企業在進行數據備份和歸檔時，可以利用標量檢索，例如根據文件的創建時間、存儲類型或自定義標簽等元數據，迅速檢索到特定日期或類型的文件，從而快速恢復歷史數據或歸檔記錄。
注意事項
地域限制
華東1（杭州）、華北2（北京）、華北3（張家口）、華南1（深圳）、華南3（廣州）、中國香港、新加坡地域的Bucket支持使用標量檢索功能。
Bucket限制
默認只支持為文件數量在100億以下的Bucket開啟標量檢索功能。
費用說明
標量檢索目前是公測階段。使用標量檢索功能會產生Object的元數據管理費用以及檢索次數費用，但公測期間暫不收費。關于數據索引計費項的更多信息，請參見數據索引費用。
建立索引所需時間
開啟標量檢索功能時，建立索引所需時間與Bucket內存量的文件數量成正比。文件數量越多，建立索引的時間越長。 一般來說，1000萬個文件初次建立索引的時間約為1小時，10億個文件初次建立索引的時間約為1天，100億個文件初次建立索引的時間約為2~3 天，該時間僅供參考。
分片上傳
對于通過分片上傳生成的Object，查詢結果中只顯示已通過CompleteMultipartUpload操作將碎片（Part）合成的完整Object，不顯示已初始化但未完成（Complete）或者未中止（Abort）的碎片。
操作步驟
使用OSS控制臺
以查找所有文件大小小于500KB，最后更新時間在2024年9月11日0:00至2024年9月12日0:00的文件，輸出結果按文件大小升序排列，并按文件大小統計最大值為例：
Bucket為廣州地域
登錄OSS管理控制臺。
單擊Bucket 列表，然后單擊目標Bucket名稱。
在左側導航欄， 選擇。
在數據索引頁面，單擊立即開啟。
選擇標量檢索，單擊確認開啟。
說明開啟標量檢索需要等待一定的時間，具體等待時長取決于Bucket中Object的數量。
按以下說明設置OSS元數據檢索條件，其他參數保留默認設置。
將最后修改時間設置為2024年9月11日0:00至2024年9月12日0:00。
文件大小設置為小于500KB。
設置輸出方式。
對象排序方式選擇按照文件大小升序排列。
數據聚合選擇按照文件大小的最大值聚合輸出。
單擊立即查詢。符合檢索條件的所有文件共2個，如下圖所示，文件最大為434KB。
如需了解完整的檢索條件和輸出設置，請參見檢索條件及輸出設置。
Bucket為杭州、北京、張家口、深圳、中國香港、新加坡地域
登錄OSS管理控制臺。
單擊Bucket 列表，然后單擊目標Bucket名稱。
在左側導航欄， 選擇。
開啟元數據管理。
說明開啟元數據管理需要等待一定的時間，具體等待時長取決于Bucket中Object的數量。
按以下說明設置對象基礎過濾條件，其他參數保留默認設置。
將最后修改時間設置為2024年9月11日0:00至2024年9月12日0:00。
文件大小設置為小于500KB。
展開更多過濾條件。
對象排序方式選擇按照文件大小升序排列。
數據聚合選擇按照文件大小的最大值聚合輸出。
單擊查詢。符合檢索條件的所有文件共2個，如下圖所示，文件最大為434KB。
如需了解完整的檢索條件和輸出設置，請參見檢索條件及輸出設置。
使用阿里云SDK
僅Java SDK、Python SDK以及Go SDK支持通過標量檢索功能查詢滿足指定條件的Object。使用標量檢索功能前，您需要為指定Bucket開啟元數據管理功能。關于標量檢索的代碼示例，請參見SDK簡介。
import com.aliyun.oss.ClientException;
import com.aliyun.oss.OSS;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.OSSException;
import com.aliyun.oss.model.*;
import java.util.ArrayList;
import java.util.List;
public class Demo {
// Endpoint以華東1（杭州）為例，其它Region請按實際情況填寫。
private static String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
// 填寫Bucket名稱，例如examplebucket。
private static String bucketName = "examplebucket";
public static void main(String[] args) throws Exception {
// 從環境變量中獲取訪問憑證。運行本代碼示例之前，請確保已設置環境變量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
// 創建OSSClient實例。
OSS ossClient = new OSSClientBuilder().build(endpoint, credentialsProvider);
try {
// 查詢滿足指定條件的文件（Object），并按照指定字段和排序方式列舉文件信息。
int maxResults = 20;
// 指定查詢小于1048576字節的文件，且最多返回20個結果，返回結果按升序排列。
String query = "{\"Field\": \"Size\",\"Value\": \"1048576\",\"Operation\": \"lt\"}";
String sort = "Size";
DoMetaQueryRequest doMetaQueryRequest = new DoMetaQueryRequest(bucketName, maxResults, query, sort);
Aggregation aggregationRequest = new Aggregation();
Aggregations aggregations = new Aggregations();
List<Aggregation> aggregationList = new ArrayList<Aggregation>();
// 指定聚合操作的字段名稱。
aggregationRequest.setField("Size");
// 指定聚合操作的操作符，max表示最大值。
aggregationRequest.setOperation("max");
aggregationList.add(aggregationRequest);
aggregations.setAggregation(aggregationList);
// 設置聚合操作。
doMetaQueryRequest.setAggregations(aggregations);
doMetaQueryRequest.setOrder(SortOrder.ASC);
DoMetaQueryResult doMetaQueryResult = ossClient.doMetaQuery(doMetaQueryRequest);
if(doMetaQueryResult.getFiles() != null){
for(ObjectFile file : doMetaQueryResult.getFiles().getFile()){
System.out.println("Filename: " + file.getFilename());
// 獲取標識Object的內容。
System.out.println("ETag: " + file.getETag());
// 獲取Object的訪問權限
System.out.println("ObjectACL: " + file.getObjectACL());
// 獲取Object的類型。
System.out.println("OssObjectType: " + file.getOssObjectType());
// 獲取Object的存儲類型。
System.out.println("OssStorageClass: " + file.getOssStorageClass());
// 獲取Object的標簽個數。
System.out.println("TaggingCount: " + file.getOssTaggingCount());
if(file.getOssTagging() != null){
for(Tagging tag : file.getOssTagging().getTagging()){
System.out.println("Key: " + tag.getKey());
System.out.println("Value: " + tag.getValue());
}
}
if(file.getOssUserMeta() != null){
for(UserMeta meta : file.getOssUserMeta().getUserMeta()){
System.out.println("Key: " + meta.getKey());
System.out.println("Value: " + meta.getValue());
}
}
}
} else if(doMetaQueryResult.getAggregations() != null){
for(Aggregation aggre : doMetaQueryResult.getAggregations().getAggregation()){
// 獲取聚合字段名稱。
System.out.println("Field: " + aggre.getField());
// 獲取聚合字段的操作符。
System.out.println("Operation: " + aggre.getOperation());
// 獲取聚合操作的結果值。
System.out.println("Value: " + aggre.getValue());
if(aggre.getGroups() != null && aggre.getGroups().getGroup().size() > 0){
// 獲取分組聚合的值。
System.out.println("Groups value: " + aggre.getGroups().getGroup().get(0).getValue());
// 獲取分組聚合的總個數。
System.out.println("Groups count: " + aggre.getGroups().getGroup().get(0).getCount());
}
}
} else {
System.out.println("NextToken: " + doMetaQueryResult.getNextToken());
}
} catch (OSSException oe) {
System.out.println("Error Message:" + oe.getErrorMessage());
System.out.println("Error Code:" + oe.getErrorCode());
System.out.println("Request ID:" + oe.getRequestId());
System.out.println("Host ID:" + oe.getHostId());
} catch (ClientException ce) {
System.out.println("Error Message: " + ce.getMessage());
} finally {
// 關閉OSSClient。
ossClient.shutdown();
}
}
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
from oss2.models import MetaQuery, AggregationsRequest
# 從環境變量中獲取訪問憑證。運行本代碼示例之前，請確保已設置環境變量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# Endpoint以杭州為例，其它Region請按實際情況填寫。
# 填寫Bucket名稱，例如examplebucket。
bucket = oss2.Bucket(auth, 'http://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
# 查詢滿足指定條件的Object，并按照指定字段和排序方式列舉Object信息。
# 指定查詢小于1 MB的文件，且最多返回十個結果，返回結果按升序排列。
do_meta_query_request = MetaQuery(max_results=10, query='{"Field": "Size","Value": "1048576","Operation": "lt"}', sort='Size', order='asc')
result = bucket.do_bucket_meta_query(do_meta_query_request)
# 打印Object名稱。
print(result.files[0].file_name)
# 打印Object對應的ETag。
print(result.files[0].etag)
# 打印Object類型。
print(result.files[0].oss_object_type)
# 打印Object存儲類型。
print(result.files[0].oss_storage_class)
# 打印Object的64位CRC值。
print(result.files[0].oss_crc64)
# 打印Object的訪問權限。
print(result.files[0].object_acl)package main
import (
"fmt"
"github.com/aliyun/aliyun-oss-go-sdk/oss"
"os"
)
func main() {
// 從環境變量中獲取訪問憑證。運行本代碼示例之前，請確保已設置環境變量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
provider, err := oss.NewEnvironmentVariableCredentialsProvider()
if err != nil {
fmt.Println("Error:", err)
os.Exit(-1)
}
// 創建OSSClient實例。
// yourEndpoint填寫Bucket對應的Endpoint，以華東1（杭州）為例，填寫為https://oss-cn-hangzhou.aliyuncs.com。其它Region請按實際情況填寫。
client, err := oss.New("yourEndpoint", "", "", oss.SetCredentialsProvider(&provider))
if err != nil {
fmt.Println("Error:", err)
os.Exit(-1)
}
// 指定查詢大于30字節的文件，且最多返回十個結果，返回結果按升序排列。
query := oss.MetaQuery{
NextToken: "",
MaxResults: 10,
Query: `{"Field": "Size","Value": "30","Operation": "gt"}`,
Sort: "Size",
Order: "asc",
}
// 查詢滿足指定條件的Object，并按照指定字段和排序方式列舉Object信息。
result,err := client.DoMetaQuery("examplebucket",query)
if err != nil {
fmt.Println("Error:", err)
os.Exit(-1)
}
fmt.Printf("NextToken:%s\n", result.NextToken)
for _, file := range result.Files {
fmt.Printf("File name: %s\n", file.Filename)
fmt.Printf("size: %d\n", file.Size)
fmt.Printf("File Modified Time:%s\n", file.FileModifiedTime)
fmt.Printf("Oss Object Type:%s\n", file.OssObjectType)
fmt.Printf("Oss Storage Class:%s\n", file.OssStorageClass)
fmt.Printf("Object ACL:%s\n", file.ObjectACL)
fmt.Printf("ETag:%s\n", file.ETag)
fmt.Printf("Oss CRC64:%s\n", file.OssCRC64)
fmt.Printf("Oss Tagging Count:%d\n", file.OssTaggingCount)
for _, tagging := range file.OssTagging {
fmt.Printf("Oss Tagging Key:%s\n", tagging.Key)
fmt.Printf("Oss Tagging Value:%s\n", tagging.Value)
}
for _, userMeta := range file.OssUserMeta {
fmt.Printf("Oss User Meta Key:%s\n", userMeta.Key)
fmt.Printf("Oss User Meta Key Value:%s\n", userMeta.Value)
}
}
}使用REST API
如果您的程序自定義要求較高，您可以直接發起REST API請求。直接發起REST API請求需要手動編寫代碼計算簽名。更多信息，請參見DoMetaQuery。
檢索條件及輸出設置
檢索條件
以下是完整的檢索條件，您可以根據需要進行單獨或組合設置。
檢索條件 | 說明 |
存儲類型 | 默認選中OSS支持的標準、低頻訪問、歸檔、冷歸檔和深度冷歸檔多種存儲類型。您可以按需選擇希望在查詢結果中顯示的Object存儲類型。 |
讀寫權限 | 默認選中OSS支持的四種讀寫權限ACL，即繼承Bucket、私有、公共讀以及公共讀寫。您可以按需選擇希望在查詢結果中顯示的Object讀寫權限。 |
文件名 | 支持模糊匹配和等于。如果您希望在查詢結果中顯示某個文件名，例如exampleobject.txt。您可以通過以下兩種方式匹配目標文件：
|
上傳類型 | 默認選中OSS支持的四種Object類型，您可以按需選擇希望在查詢結果中顯示的Object類型。Object類型說明如下：
|
最后修改時間 | 指定Object被最后修改的起始日期和結束日期，時間精確到秒。 |
文件大小 | 支持等于、大于、大于等于、小于和小于等于五種篩選條件，文件大小單位為KB。 |
對象版本 | 僅支持查詢當前版本Object。 |
如需根據對象Etag及標簽進行過濾查找，可輸入您希望在查詢結果中顯示的Object對應的ETag或標簽信息。
ETag僅支持精確匹配。ETag必須帶引號，示例值為"5B3C1A2E0563E1B002CC607C6689"。可輸入多個ETag，每行一個。
以鍵值對（Key-Value）的形式指定對象標簽。對象標簽的Key和Value均區分大小寫。關于標簽規則的更多信息，請參見對象標簽。
結果輸出設置
您可對輸出結果進行排序和簡單統計。
對象排序方式：支持根據最后修改時間、文件名和文件大小進行升序、降序及默認排序。您可以按需選擇并排序檢索結果，便于快速找到所需文件。
數據聚合：支持多種輸出類型，您可以對檢索結果進行去重統計、分組計數、最大值、最小值、平均值和求和等計算，便于高效分析和管理數據。
常見問題
Bucket內文件數量達到上億級別時，為什么很長時間都沒有成功建立數據索引？
1秒內大約可以為600個文件建立索引。您可以結合Bucket內的文件數量，預估建立索引所需時間。
相關文檔
標量檢索支持多項過濾條件，例如文件最后修改時間、存儲類型、讀寫權限、文件大小等。如果您希望從OSS Bucket的海量Object中篩選出指定時間范圍內的Object，請參見如何篩選OSS指定時間范圍內的文件？。