# es-index

Part of **ES**

# Elasticsearch Index Management

## Capabilities Overview

| Sub-capability | Calling Mode | Description |
|----------------|--------------|-------------|
| List Index Tables | Synchronous | Queries a list of index tables in an Elasticsearch instance. |
| Create Index | Synchronous | Creates an index with specified name, data source, schema, and configuration details. |
| Delete Index | Synchronous | Permanently deletes an existing Elasticsearch index. |
| Modify Index | Synchronous | Updates configuration and data source settings of an existing index. |
| Get Index Details | Synchronous | Retrieves detailed metadata, configuration, and data source information about a specific index. |
| List Indexes | Synchronous | Gets a list of all indexes in an Elasticsearch instance with version and status details. |
| Rebuild Index | Synchronous | Triggers a rebuild operation for an index with specified data source and build parameters. |
| Manage Index Versions | Synchronous | Creates, deletes, modifies, and publishes different versions of an index. |
| Manage Index Files | Synchronous | Gets details and modifies files associated with specific index versions. |
| Manage Index Partitions | Synchronous | Modifies partition configuration including shard count and concurrency settings. |
| Manage Index Online Strategy | Synchronous | Gets and modifies the online deployment strategy for indexes. |
| Manage Online Configuration | Synchronous | Modifies online configuration settings for Elasticsearch instance nodes. |
| Control Index State | Synchronous | Starts, stops, or recovers Elasticsearch indexes. |
| Retrieve Index | Synchronous | Accesses and retrieves index data and metadata through standard Elasticsearch endpoints. |

## API Calling Patterns

### Authentication
The primary authentication method is Bearer Token authentication:
- Header format: `Authorization: Bearer <your_api_key>`
- Environment variable: `DASHSCOPE_API_KEY`
- Set your API key as an environment variable and reference it in requests

### Service Endpoint
APIs use region-specific endpoints following this pattern:
- China regions: `https://api.aliyun.com/openapi/ha3/instances/{instanceId}/...`
- International regions: `https://api.alibabacloud.com/openapi/ha3/instances/{instanceId}/...`

Common regions include:
- cn-hangzhou
- cn-shanghai  
- cn-beijing

### Synchronous API Pattern
All Elasticsearch Index Management APIs follow a synchronous calling pattern:
1. Make an HTTP request (GET, POST, PUT, DELETE) to the appropriate endpoint
2. Include required parameters in the URL path, query string, or request body
3. Add the Authorization header with your Bearer token
4. Receive an immediate JSON response with requestId and result fields
5. Handle success or error responses based on HTTP status codes

No polling or async handling is required since all operations complete synchronously.

## Parameter Reference

### Create Index

| Parameter | Type | Required | Default | Constraints | Description |
|-----------|------|----------|---------|-------------|-------------|
| instanceId | string | true | - | - | The instance ID |
| name | string | false | - | - | The name of the index |
| dataSource | string | false | - | - | The name of the data source |
| domain | string | false | - | - | The data center of the data source |
| content | string | false | - | - | The index schema |
| partition | integer | false | - | - | The number of data shards |
| dataSourceInfo | object | false | - | - | Information about the data source (required for new Vector Search Edition) |
| type | string | false | - | one of: odps, swift, saro, oss | The type of the data source |
| dryRun | boolean | false | - | one of: true, false | Specifies whether to perform a dry run |

### Manage Index Versions

| Parameter | Type | Required | Default | Constraints | Description |
|-----------|------|----------|---------|-------------|-------------|
| instanceId | string | true | - | - | The instance ID |
| indexName | string | true | - | - | The index name |
| versionName | string | true | - | - | The name of the version |
| clusterName | string | true | - | - | The name of the cluster |
| buildDeployId | string | false | - | - | The deployment ID of the data source |

### Control Index State

| Parameter | Type | Required | Default | Constraints | Description |
|-----------|------|----------|---------|-------------|-------------|
| instanceId | string | true | - | - | The instance ID |
| indexName | string | true | - | - | The index name |
| dataSourceName | string | false | - | - | The name of the data source |
| generation | string | false | - | - | The ID of the full index version |
| buildDeployId | integer | false | - | - | The deployment ID of the data source |

### Manage Index Online Strategy

| Parameter | Type | Required | Default | Constraints | Description |
|-----------|------|----------|---------|-------------|-------------|
| instanceId | string | true | - | - | The instance ID |
| dataSourceName | string | true | - | - | The name of the data source |
| deployName | string | true | - | - | The name of the data center deployment |
| indexName | string | true | - | - | The index name |
| changeRate | integer | false | - | - | The index change rate |

## Code Examples

### List All Indexes - Python - All Regions

```python
import requests

url = "https://api.aliyun.com/openapi/ha3/instances/ose-test1/indexes"
headers = {
    "Authorization": "Bearer $DASHSCOPE_API_KEY",
    "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)
print(response.json())
```

### Create Index - curl - All Regions

```bash
curl -X POST https://api.aliyun.com/openapi/ha3/instances/ha3_instance_name/actions/build-index \
-H "Content-Type: application/json" \
-d '{
    "dataSourceName": "my_data_source",
    "domain": "test",
    "indexes": [
      "index1",
      "index2"
    ],
    "dataSourceType": "odps",
    "partition": "20201010",
    "dataTimeSec": 1640867288
}'
```

### Delete Index Version - bash - All Regions

```bash
curl -X DELETE \
  'https://api.aliyun.com/openapi/ha3/instances/ose-test1/indexes/my_index/versions/version1' \
  -H 'Authorization: Bearer $DASHSCOPE_API_KEY'
```

### Get Index File Details - curl - All Regions

```bash
curl -X GET 'https://api.aliyun.com/openapi/ha3/instances/ose-test1/indexes/index1/versions/version1?fileName=/root/test.txt' \
-H 'Authorization: Bearer $DASHSCOPE_API_KEY'
```

### Modify Index Partition - curl - All Regions

```bash
curl -X PUT 'https://api.aliyun.com/openapi/ha3/instances/{instanceId}/index-partition' \
-H 'Authorization: Bearer <your-api-key>' \
-H 'Content-Type: application/json' \
-d '{
  "dataSourceName":"ha-cn-pl32n3bi904_d",
  "domainName":"pre_domain_1",
  "generation":"1633293829",
  "indexInfos":[
    {
      "indexName":"atest2",
      "partitionCount":2
    }
  ]
}'
```

### Stop Index - curl - All Regions

```bash
curl -X POST 'https://searchengine.aliyuncs.com/openapi/ha3/instances/{instanceId}/indexes/{indexName}/stopIndex' \
-H 'Authorization: Bearer $API_KEY' \
-H 'Content-Type: application/json' \
-d '{}'
```

### Retrieve Index - Python - All Regions

```python
from elasticsearch import Elasticsearch

es = Elasticsearch("https://your-es-cluster.com:9200", http_auth=("user", "password"))
response = es.get(index="example-index")
print(response)
```

## Response Format

```json
{
  "requestId": "10D5E615-69F7-5F49-B850-00169ADE513C",
  "result": [
    {
      "name": "es_test_1b",
      "indexStatus": "IN_USE",
      "status": "IN_USE"
    }
  ]
}
```

**Key Fields**:
- `requestId` — Unique identifier for the API request
- `result[].name` — Name of the index or table
- `result[].indexStatus` — Current status of the index (e.g., IN_USE, PUBLISH)
- `result[].status` — Operational status of the resource

## Error Handling

| Error Code | Description | Recommended Action |
|------------|-------------|-------------------|
| 400 | Bad request. The request parameters are invalid or missing. | Validate all required parameters and their formats |
| 401 | Unauthorized. The API key or credentials are invalid or not authorized. | Verify your DASHSCOPE_API_KEY environment variable |
| 403 | Forbidden. The user does not have sufficient permissions. | Check RAM permissions for searchengine:* actions |
| 404 | Not Found. The specified instance or resource does not exist. | Confirm instanceId, indexName, and other identifiers |
| 429 | Too Many Requests - Rate limit exceeded. | Implement exponential backoff and retry logic |
| 500 | Internal Server Error. An unexpected error occurred. | Retry the request after a short delay |
| 503 | Service Unavailable. The service is temporarily unavailable. | Wait and retry; check service status |

### Rate Limits & Retry
- Standard rate limit: 100 QPS per account/instance
- Implement exponential backoff with jitter for retries
- Respect Retry-After header when present in 429 responses
- Consider batching operations to stay within limits

## Environment Requirements

- Set environment variable: `export DASHSCOPE_API_KEY=your_api_key_here`
- For Python Elasticsearch client: `pip install elasticsearch>=7.10.0`
- Ensure network connectivity to api.aliyun.com or api.alibabacloud.com

## FAQ

Q: How do I authenticate my API requests?
A: Use Bearer Token authentication by setting the Authorization header to "Bearer $DASHSCOPE_API_KEY" where DASHSCOPE_API_KEY is your environment variable containing the API key.

Q: What's the difference between List Index Tables and List Indexes?
A: List Index Tables provides basic table information with status, while List Indexes returns comprehensive details including versions, data sources, configurations, and metadata for all indexes in an instance.

Q: Can I modify an index without downtime?
A: Yes, many modifications can be performed online. However, some structural changes may require rebuilding the index. Use the dryRun parameter to validate changes before applying them.

Q: How do I handle rate limiting?
A: Implement exponential backoff retry logic with jitter. Monitor your QPS usage and consider batching operations during off-peak hours if you consistently hit limits.

Q: What data source types are supported?
A: Supported data source types include odps, swift, saro, and oss. Each type has specific configuration requirements for endpoints, credentials, and project/table specifications.

## Pricing & Billing

### Billing Model
Per-request billing model where each API call counts as one request regardless of success or failure.

### Price Reference

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

### Free Tier
Monthly free allowances ranging from 100 to 1000 free calls depending on the specific API operation.

### Usage Limits
- Rate limits: 100 QPS per account/instance
- Request size limits: 8KB to 8192 characters depending on the API
- Field limits: Up to 1000 fields for index creation operations

### Billing Notes
- Each API call is billed once upon execution
- Failed requests still count toward billing and quotas
- Free tier resets monthly
- Additional charges may apply for large schemas or high-frequency operations