# es-vector

Part of **ES**

# Elasticsearch Vector Search

## Capabilities Overview

| Sub-capability | Calling Mode | Description |
|----------------|--------------|-------------|
| List Vector Query Result | Synchronous | Retrieves the results of a vector query test in Vector Search Edition. This API allows users to fetch query results by specifying the instance ID and query parameters. |

## API Calling Patterns

### Authentication
The primary authentication method is Bearer Token authentication.

- Include the header: `Authorization: Bearer <your_api_key>`
- Store your API key in the environment variable: `DASHSCOPE_API_KEY`
- Alternative methods may exist, but Bearer Token is the recommended approach for this API.

### Service Endpoint
The API uses region-specific endpoints:

- China region: `https://api.aliyun.com/api/searchengine/2021-10-25/ListVectorQueryResult`
- International region: `https://api.alibabacloud.com/api/searchengine/2021-10-25/ListVectorQueryResult`

Common regions include cn-hangzhou, cn-shanghai, and cn-beijing.

### Synchronous Pattern
The ListVectorQueryResult API follows a synchronous calling pattern:

1. Send a POST request to the appropriate endpoint with required parameters
2. Include the Authorization header with your Bearer token
3. The server processes the request immediately and returns results in the response body
4. Parse the JSON response to extract the query results

No polling or async handling is required since this is a synchronous API.

## Parameter Reference

### List Vector Query Result

| Parameter | Type | Required | Default | Constraints | Description |
|-----------|------|----------|---------|-------------|-------------|
| instanceId | string | Yes | - | - | The instance ID. |
| path | string | No | - | - | The request path. |
| queryType | string | No | - | one of: vector, primary_key, vector_text | The query type. Valid values: vector, primary_key, and vector_text. |
| vectorQueryType | string | No | - | one of: vector, image, text | The vector query type. Valid values: vector, image, and text. |
| body | object | No | - | - | The request body. |

## Code Examples

### List Vector Query Result - JSON - All Regions

```json
{
  "requestId": "022F36C7-9FB4-5D67-BEBC-3D14B0984463",
  "result": "{}"
}
```

### List Vector Query Result - Python - China

```python
import os
import requests
import json

# Set your API key as environment variable: export DASHSCOPE_API_KEY='your-api-key'
api_key = os.getenv("DASHSCOPE_API_KEY")
url = "https://api.aliyun.com/api/searchengine/2021-10-25/ListVectorQueryResult"

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

payload = {
    "instanceId": "your-instance-id",
    "queryType": "vector",
    "vectorQueryType": "text"
}

response = requests.post(url, headers=headers, data=json.dumps(payload))
print(response.json())
```

### List Vector Query Result - curl - International

```bash
curl -X POST \
  https://api.alibabacloud.com/api/searchengine/2021-10-25/ListVectorQueryResult \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceId": "your-instance-id",
    "queryType": "vector",
    "vectorQueryType": "text"
  }'
```

### List Vector Query Result - Java - China

```java
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.HashMap;
import java.util.Map;

public class VectorSearchExample {
    public static void main(String[] args) throws IOException, InterruptedException {
        String apiKey = System.getenv("DASHSCOPE_API_KEY");
        String url = "https://api.aliyun.com/api/searchengine/2021-10-25/ListVectorQueryResult";
        
        Map<String, Object> payload = new HashMap<>();
        payload.put("instanceId", "your-instance-id");
        payload.put("queryType", "vector");
        payload.put("vectorQueryType", "text");
        
        String jsonPayload = new com.fasterxml.jackson.databind.ObjectMapper().writeValueAsString(payload);
        
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Authorization", "Bearer " + apiKey)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(jsonPayload))
            .build();
            
        HttpClient client = HttpClient.newHttpClient();
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        
        System.out.println(response.body());
    }
}
```

## Response Format

```json
{
  "requestId": "022F36C7-9FB4-5D67-BEBC-3D14B0984463",
  "result": "{}"
}
```

**Key Fields**:
- `requestId` — Unique identifier for the request, useful for debugging and tracking
- `result` — Contains the actual vector query results in JSON format

## Error Handling

| Error Code | Description | Recommended Action |
|------------|-------------|-------------------|
| 400 | Bad Request. The request parameters are invalid or missing required fields. | Verify all required parameters are provided and valid |
| 401 | Unauthorized. The API key or credentials are invalid or not authorized to access the resource. | Check your API key and ensure it has proper permissions |
| 403 | Forbidden. The user does not have sufficient permissions to perform this operation. | Contact your administrator to grant necessary permissions |
| 404 | Not Found. The specified instance ID does not exist or is not accessible. | Verify the instance ID exists and is correctly spelled |
| 500 | Internal Server Error. An unexpected error occurred on the server side. | Retry the request after a short delay; contact support if persistent |
| 503 | Service Unavailable. The service is temporarily unavailable due to overload or maintenance. | Implement exponential backoff and retry logic |

## Environment Requirements

- Set the environment variable: `export DASHSCOPE_API_KEY=your_api_key`
- For Python: `pip install requests` (for the HTTP client example)
- For Java: Include Jackson library for JSON processing

## FAQ

Q: What vector search algorithms are supported by Elasticsearch Vector Search Edition?
A: The service supports multiple algorithms including Linear, Quantized clustering, HNSW, QGraph, CAGRA, and DiskANN for large-scale datasets that exceed available memory.

Q: How do I authenticate my requests to the Vector Search API?
A: Use Bearer Token authentication by including the header `Authorization: Bearer <your_api_key>` where your API key is stored in the `DASHSCOPE_API_KEY` environment variable.

Q: What are the valid values for queryType and vectorQueryType parameters?
A: queryType accepts "vector", "primary_key", or "vector_text". vectorQueryType accepts "vector", "image", or "text".

Q: Can I use this API for real-time vector similarity search?
A: Yes, the Vector Search Edition supports real-time data synchronization and high-performance querying for vector similarity search applications.

Q: What field types are required for vector search in Elasticsearch?
A: Vector fields should use the DOUBLE_ARRAY field type, and you may also need TEXT field types for general-purpose analyzers depending on your use case.

## Pricing & Billing

### Billing Model
Per-request billing model where each API call is charged regardless of result size.

### Price Reference

| Tier | Input Price | Output Price |
|------|-------------|--------------|
| default | 0.001 / | 0.001 / |

### Free Tier
Monthly free quota of 1000 requests.

### Usage Limits
Maximum 8192 characters per request.

### Billing Notes
Billing applies to every API call, including failed requests which still count toward your quota.