# es-data-query

Part of **ES**

# Elasticsearch Data Query

## Capabilities Overview

| Sub-capability | Calling Mode | Description |
|----------------|--------------|-------------|
| Query Merged Table Info | Synchronous | Queries the information about a wide table generated after a JOIN operation is performed on multiple tables in OpenSearch. |

## API Calling Patterns

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

- Include the header: `Authorization: Bearer <your-api-key>`
- Store your API key in the environment variable: `ALIBABA_CLOUD_API_KEY`
- Alternative methods (e.g., STS tokens) are supported in other Alibaba Cloud services but **not recommended** for this API—use Bearer Token as shown in all official examples.

### Service Endpoint
The API uses a single global endpoint:

- Base URL: `https://opensearch.api.aliyun.com/v4/openapi/assist/schema/actions/merge`
- Method: `POST`
- Region: This endpoint is region-agnostic (`all` regions)

### Synchronous Request Pattern
This API follows a standard synchronous request-response flow:

1. Send a `POST` request to the endpoint with JSON body and `Authorization` header
2. The server validates permissions, instance specs, and request structure
3. On success, returns merged table metadata immediately in JSON format
4. No polling or async handling is required—response is returned in a single round trip

Key headers:
- `Content-Type: application/json`
- `Authorization: Bearer <your-api-key>`

## Parameter Reference

### Query Merged Table Info

| Parameter | Type | Required | Default | Constraints | Description |
|-----------|------|----------|---------|-------------|-------------|
| spec | string | false | opensearch.share.common | — | The specifications of the OpenSearch instance. Used to check whether the instance meets special limits for exclusive instances. |
| body | object | false | — | Must contain `tables` if provided | The request body containing table and index schemas for the JOIN operation. |

#### Body Sub-parameters

| Parameter | Type | Required | Default | Constraints | Description |
|-----------|------|----------|---------|-------------|-------------|
| tables | object | true (if body present) | {} | Non-empty object | The table schema defining the structure of tables involved in the JOIN. |
| indexes | object | false | {} | — | The index schema for optimizing the JOIN operation. |

## Code Examples

### Query Merged Table Info - curl - all

```bash
POST /v4/openapi/assist/schema/actions/merge HTTP/1.1
Host: opensearch.api.aliyun.com
Authorization: Bearer <your-api-key>
Content-Type: application/json

{
  "spec": "opensearch.share.common",
  "body": {
    "tables": {},
    "indexes": {}
  }
}
```

### Query Merged Table Info - Python - all

```python
import requests
import os

url = "https://opensearch.api.aliyun.com/v4/openapi/assist/schema/actions/merge"
headers = {
    "Authorization": f"Bearer {os.getenv('ALIBABA_CLOUD_API_KEY')}",
    "Content-Type": "application/json"
}
data = {
    "spec": "opensearch.share.common",
    "body": {
        "tables": {},
        "indexes": {}
    }
}

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

### Query Merged Table Info with Custom Tables - Python - all

```python
import requests
import os

url = "https://opensearch.api.aliyun.com/v4/openapi/assist/schema/actions/merge"
headers = {
    "Authorization": f"Bearer {os.getenv('ALIBABA_CLOUD_API_KEY')}",
    "Content-Type": "application/json"
}
data = {
    "spec": "opensearch.share.common",
    "body": {
        "tables": {
            "user_table": {"id": "long", "name": "text"},
            "order_table": {"user_id": "long", "amount": "double"}
        },
        "indexes": {
            "user_id_idx": ["user_table.id", "order_table.user_id"]
        }
    }
}

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

### Minimal Query - curl - all

```bash
curl -X POST https://opensearch.api.aliyun.com/v4/openapi/assist/schema/actions/merge \
  -H "Authorization: Bearer $ALIBABA_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"spec": "opensearch.share.common"}'
```

## Response Format

```json
{
  "requestId": "ABCDEFGH",
  "result": {
    "primaryKey": "-",
    "mergeTable": {
      "test": "test",
      "test2": 1
    },
    "fromTable": {
      "test": "test",
      "test2": 1
    }
  }
}
```

**Key Fields**:
- `requestId` — Unique identifier for the API request, useful for debugging
- `result.mergeTable` — Schema of the resulting wide table after JOIN
- `result.fromTable` — Schema of the source tables used in the JOIN
- `result.primaryKey` — Primary key field of the merged table (may be "-" if not defined)

## Error Handling

| Error Code | Description | Recommended Action |
|------------|-------------|---------------------|
| 400 | Bad Request: The request body is invalid or missing required fields. | Validate JSON structure; ensure `tables` is present if `body` is used |
| 401 | Unauthorized: The API key is missing, invalid, or does not have sufficient permissions. | Check `ALIBABA_CLOUD_API_KEY` value and IAM permissions for `opensearch:GenerateMergedTable` |
| 403 | Forbidden: The user does not have permission to perform this operation. | Contact account administrator to grant required OpenSearch permissions |
| 404 | Not Found: The specified resource (e.g., table) does not exist. | Verify that referenced tables exist in your OpenSearch instance |
| 500 | Internal Server Error: An unexpected error occurred on the server side. | Retry with exponential backoff; contact support if persistent |
| 503 | Service Unavailable: The service is temporarily unavailable due to overload or maintenance. | Wait and retry; check Alibaba Cloud status dashboard |

## Pricing & Billing

### Billing Model
Per-request billing: charged per successful API call.

### Price Reference

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

### Free Tier
Monthly free quota of 1,000 calls.

### Usage Limits
Maximum 100 QPS per Alibaba Cloud account.

### Billing Notes
Billing occurs only for successful requests. Failed requests (e.g., 4xx/5xx responses) are not billed.

## FAQ

Q: What OpenSearch edition is required for this API?
A: This API works with OpenSearch Retrieval Engine Edition and Vector Search Edition (V3.7.4+). Ensure your instance version supports JOIN operations and TVFs.

Q: Can I use this API without specifying the `body` parameter?
A: Yes—the `body` parameter is optional. If omitted, the API may return minimal or default schema information depending on instance configuration.

Q: How do I handle JOIN operations between more than two tables?
A: Define all participating tables in the `tables` object within the `body`. Use the `indexes` field to optimize multi-table JOIN performance.

Q: Is there a size limit for the `tables` schema definition?
A: While not explicitly documented, extremely large schemas may trigger request size limits (typically 1–10 MB). Split complex operations if needed.

Q: Why am I getting a 401 error even with a valid API key?
A: Ensure your API key has the `opensearch:GenerateMergedTable` permission. Keys created for other Alibaba Cloud services (e.g., ECS, OSS) won’t work—use an OpenSearch-specific key.