Use PHP SDK V2 to query objects with AISearch - Object Storage Service

OSS AISearch lets you search objects in a bucket by semantic content, OSS metadata, multimedia metadata, ETags, object tags, and custom metadata. This topic shows how to use AISearch with the OSS SDK for PHP V2.

Prerequisites

Before you begin, ensure that you have:

PHP and Composer installed, with the OSS SDK for PHP V2 dependency added (alibabacloud/oss-v2)
OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET set as environment variables
An OSS bucket in a supported region

The examples in this topic use the China (Hangzhou) region (cn-hangzhou) and a public endpoint. To access OSS from other Alibaba Cloud services within the same region, use an internal endpoint. For more information, see OSS regions and endpoints.

Setup

All examples in this topic share the same client initialization. Run this setup once before calling any AISearch operation.

<?php

require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// Read credentials from environment variables.
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider($credentialsProvider);
$cfg->setRegion('<region>');        // e.g., cn-hangzhou
// $cfg->setEndpoint('<endpoint>'); // Uncomment to use a custom endpoint.

$client = new Oss\Client($cfg);

Replace <region> with the region where your bucket is located.

For more examples of how to configure credentials, see Configure access credentials. For more client configuration options, see Configure a client.

Enable AISearch

// Enable AISearch on the specified bucket.
// Pass 'semantic' as the mode to activate AI-powered semantic (vector) retrieval.
$request = new Oss\Models\OpenMetaQueryRequest($bucket, 'semantic');
$result  = $client->openMetaQuery($request);

echo 'status code: ' . $result->statusCode . PHP_EOL;
echo 'request ID: '  . $result->requestId  . PHP_EOL;

Get metadata index status

// Retrieve the current status of the metadata index for the bucket.
$request = new Oss\Models\GetMetaQueryStatusRequest(
    bucket: $bucket
);
$result = $client->getMetaQueryStatus($request);

echo 'status code: ' . $result->statusCode . PHP_EOL;
echo 'request ID: '  . $result->requestId  . PHP_EOL;
echo 'meta query status: ' . var_export($result->metaQueryStatus, true) . PHP_EOL;

Query objects

The following example queries image objects larger than 30 bytes that semantically match the phrase "Overlook the snow-covered forest". Results are limited to 99 objects.

// Query objects that match a semantic search phrase and a structured size filter.
$request = new Oss\Models\DoMetaQueryRequest(
    $bucket,
    new Oss\Models\MetaQuery(
        maxResults:  99,
        query:       'Overlook the snow-covered forest', // Natural language query for semantic search.
        mediaTypes:  new Oss\Models\MetaQueryMediaTypes('image'),
        simpleQuery: '{"Operation":"gt", "Field": "Size", "Value": "30"}',
    ),
    'semantic' // Use 'semantic' mode to enable AI-powered vector retrieval.
);

$result = $client->doMetaQuery($request);

echo 'status code: ' . $result->statusCode . PHP_EOL;
echo 'request ID: '  . $result->requestId  . PHP_EOL;
var_export($result); // The matched objects and their metadata.

Key parameters for MetaQuery:

Parameter	Description	Example value
`maxResults`	Maximum number of objects to return	`99`
`query`	Natural language phrase for semantic search	`'Overlook the snow-covered forest'`
`mediaTypes`	Filter by media type	`new Oss\Models\MetaQueryMediaTypes('image')`
`simpleQuery`	Structured filter in JSON format	`'{"Operation":"gt", "Field": "Size", "Value": "30"}'`

Disable AISearch

// Disable AISearch on the specified bucket.
$request = new \AlibabaCloud\Oss\V2\Models\CloseMetaQueryRequest(
    bucket: $bucket
);
$result = $client->closeMetaQuery($request);

echo 'status code: ' . $result->statusCode . PHP_EOL;
echo 'request ID: '  . $result->requestId  . PHP_EOL;

What's next

For a complete runnable sample, see the GitHub example.
For AISearch concepts and use cases, see AISearch.
For the underlying API operations, see Data indexing.