# pai-feature_store

Part of **PAI**

# Platform for AI (PAI) Feature Store

## Capabilities Overview

| Sub-capability | Calling Pattern | Description |
|--------|----------|------|
| Manage Datasources | Synchronous | Get datasource details and metadata for tables. |
| Manage Feature Views | Synchronous | Create, delete, get, list, update, publish, and query online features from feature views. |
| Manage Feature Entities | Synchronous | Create, delete, get, and list feature entities. |
| Manage Label Tables | Synchronous | Create, get, and update label table attributes. |
| Manage Model Features | Synchronous | Create, delete, get, list, update model features and their feature store configurations. |
| Manage Projects | Synchronous | Get project details and list feature views, features, and entities within projects. |
| Manage Tasks | Synchronous | Retrieve task details in the feature store. |

## API Calling Patterns

### Authentication
The primary authentication method is Bearer Token authentication using the `DASHSCOPE_API_KEY` environment variable.

- **Header format**: `Authorization: Bearer <your_api_key>`
- **Environment variable**: `DASHSCOPE_API_KEY`
- Set your API key as an environment variable and reference it in your requests

### Service Endpoint (Endpoint)
The Feature Store APIs use region-specific endpoints with the following pattern:

- **Base URL pattern**: `https://api.aliyun.com/api/PaiFeatureStore/2023-06-21/{operation}`
- **International endpoints**: `https://api.alibabacloud.com/api/PaiFeatureStore/2023-06-21/{operation}`
- **Common regions**: cn-hangzhou, cn-shanghai, cn-beijing

### Synchronous API Pattern
All Feature Store APIs follow a synchronous calling pattern:

1. **Make HTTP request**: Send a GET, POST, PUT, or DELETE request to the appropriate endpoint
2. **Include authentication**: Add the `Authorization: Bearer $DASHSCOPE_API_KEY` header
3. **Provide parameters**: Include required parameters in the URL query string (GET/DELETE) or request body (POST/PUT)
4. **Receive immediate response**: The API returns a JSON response with the requested data or operation result
5. **Handle response**: Parse the JSON response to extract the required information or check for errors

For operations that may take longer to complete (like data imports), the API returns a Task ID that can be used with the GetTask API to monitor progress.

## Parameter Reference

### Manage Datasources

| Parameter | Type | Required | Default | Constraints | Description |
|------|------|------|--------|------|------|
| InstanceId | string | true | | | The ID of the instance. Call the ListInstances operation to obtain this ID. |
| DatasourceId | string | false | | | The ID of the datasource. Call the ListDatasources operation to obtain this ID. |
| Name | string | false | | | The name of the datasource. |
| WorkspaceId | string | false | | | The ID of the workspace. Call the ListWorkspaces operation to obtain this ID. |
| Type | string | false | | one of: Hologres, GraphCompute, Redis, MaxCompute | The datasource type. |
| Uri | string | false | | | The URI of the resource. |
| Config | string | false | | | The configuration of the resource. |
| TableName | string | false | | | The name of the data table. |
| PageSize | integer | false | 10 | | The number of data sources per page. |
| PageNumber | integer | false | 1 | | The page number. Pages start from 1. |
| Order | string | false | | one of: Asc, Desc | The sort order. |
| SortBy | string | false | | | The field to sort by. |

### Manage Feature Views

| Parameter | Type | Required | Default | Constraints | Description |
|------|------|------|--------|------|------|
| InstanceId | string | true | | | The instance ID. Call the ListInstances API to get this ID. |
| FeatureViewId | string | false | | | The ID of the feature view. Call the ListFeatureViews operation to obtain this ID. |
| ProjectId | string | false | | | The ID of the project. |
| FeatureEntityId | string | false | | | The ID of the feature entity. |
| Name | string | false | | | The name of the feature view. |
| Type | string | false | | one of: Batch, Stream | The type of the feature view. |
| WriteMethod | string | false | | one of: ByReadyMadeTable, Custom | The write method. |
| WriteToFeatureDB | boolean | false | | one of: true, false | Specifies whether to write data to the online feature store. |
| RegisterTable | string | false | | | The name of the table to register. |
| RegisterDatasourceId | string | false | | | The ID of the data source to which the table to be registered belongs. |
| SyncOnlineTable | boolean | false | | one of: true, false | Specifies whether to synchronize the online feature table. |
| TTL | integer | false | | | The time-to-live (TTL) of the feature view, in days. |
| Tags | array | false | | | The tags of the feature view. |
| Config | string | false | | | The configurations of the feature view. |
| Fields | array<object> | false | | | The fields. |
| JoinIds | array | false | | | The list of join IDs to query. |
| Partitions | object | false | | | The partitions to publish. |
| Mode | string | false | | one of: Overwrite, Merge | The synchronization mode. |
| EventTime | string | false | | format: ISO 8601 | The event time of the data to be published. |
| OfflineToOnline | boolean | false | | | Specifies whether to synchronize data from the offline table to the online store. |

### Manage Feature Entities

| Parameter | Type | Required | Default | Constraints | Description |
|------|------|------|--------|------|------|
| InstanceId | string | true | | | The instance ID. To get this ID, call the ListInstances operation. |
| FeatureEntityId | string | false | | | The ID of the feature entity. Call the ListFeatureEntities operation to obtain the ID. |
| JoinId | string | false | | | The join key that links feature views to the feature entity. |
| Name | string | false | | | The feature entity name. |
| ProjectId | string | false | | | The project ID. To get this ID, call the ListInstances operation. |
| ParentFeatureEntityId | string | false | | | The parent feature entity ID. |
| PageNumber | integer | false | 1 | range 1 to infinity | The page number. Values start at 1. |
| PageSize | integer | false | 10 | range 1 to 100 | The number of entries to return on each page. |
| Owner | string | false | | | The Alibaba Cloud account ID of the creator. |
| FeatureEntityIds | array | false | | max length 100 items | Filters the results by a list of feature entity IDs. |

### Manage Label Tables

| Parameter | Type | Required | Default | Constraints | Description |
|------|------|------|--------|------|------|
| InstanceId | string | true | | | The instance ID. You can call the ListInstances operation to query the ID of the instance. |
| LabelTableId | string | false | | | The label table ID. You can obtain this ID by calling the ListLabelTables operation. |
| ProjectId | string | false | | | The project ID. You can call the ListProjects operation to query the ID of the project. |
| Name | string | false | | | The name of the label table. |
| DatasourceId | string | false | | | The ID of the data source. You can call the ListDatasources operation to query the ID of the data source. |
| Fields | array<object> | false | | | The fields. |
| Fields[].Name | string | false | | | The field name. |
| Fields[].Type | string | false | | | The field type. |
| Fields[].Attributes | array | false | | one of: Partition, FeatureField, FeatureGenerationReserveField, EventTime, LabelField | The field attributes. |

### Manage Model Features

| Parameter | Type | Required | Default | Constraints | Description |
|------|------|------|--------|------|------|
| InstanceId | string | true | | | The ID of the instance. To obtain this ID, call the ListInstances operation. |
| ModelFeatureId | string | false | | | The ID of the model feature. To obtain this ID, call the ListModelFeatures operation. |
| ProjectId | string | false | | | The ID of the project. To obtain this ID, call the ListProjects operation. |
| Name | string | false | | | The model feature name. |
| LabelTableId | string | false | | | The ID of the label table. To obtain this ID, call the ListLabelTables operation. |
| Features | array<object> | false | | | A list of features. |
| FeatureViewId | string | false | | | The ID of the feature view. To obtain this ID, call the ListFeatureViews operation. |
| AliasName | string | false | | | The feature alias. |
| Type | string | false | | one of: INT32, INT64, FLOAT, DOUBLE, STRING, BOOLEAN, TIMESTAMP | The data type of the feature. |
| SequenceFeatureViewIds | array | false | | | The IDs of sequence features. |
| LabelPriorityLevel | integer | false | 0 | range 0-2 | The priority of the label table. |

### Manage Projects

| Parameter | Type | Required | Default | Constraints | Description |
|------|------|------|--------|------|------|
| InstanceId | string | true | | | The ID of the FeatureStore instance. You can call the ListInstances operation to obtain this ID. |
| ProjectId | string | false | | | The project ID. You can call the ListProjects operation to obtain the project ID. |
| Name | string | false | | 2 to 18 characters, starts with a letter, contains only letters, digits, and underscores (_), regex: ^[a-zA-Z][a-zA-Z0-9_]+$ | The name of the project. |
| WorkspaceId | string | false | | | The ID of the PAI workspace. You can call the ListWorkspaces operation to obtain this ID. |
| Description | string | false | | | The description of the project. |
| OfflineDatasourceId | string | false | | | The ID of the offline data source, which must be of the MaxCompute type. |
| OfflineLifeCycle | integer | false | 0 | | The retention period in days for offline tables created by FeatureStore. |
| OnlineDatasourceId | string | false | | | The ID of the online data source. The data source type must be Hologres, Tablestore, or FeatureDB. |
| FeatureEntityName | string | false | | | Feature entity name. |

### Manage Tasks

| Parameter | Type | Required | Default | Constraints | Description |
|------|------|------|--------|------|------|
| InstanceId | string | true | | | The instance ID. Call the ListInstances API to obtain this ID. |
| TaskId | string | false | | | The task ID. Call the ListTasks API to obtain this ID. |

## Code Examples

### Create Datasource - curl - all

```curl
curl -X POST https://api.aliyun.com/api/PaiFeatureStore/2023-06-21/CreateDatasource?InstanceId=featureStore-cn-test1 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-d '{
  "Name": "datasource1",
  "WorkspaceId": "234",
  "Type": "Hologres",
  "Uri": "igraph_instance1",
  "Config": "{\"address\": \"\"}"
}'
```

### Get Datasource Details - python - all

```python
import requests

url = "https://api.aliyun.com/api/PaiFeatureStore/2023-06-21/GetDatasource"
params = {
    "InstanceId": "fs-********",
    "DatasourceId": "datasource1"
}
headers = {
    "Authorization": "Bearer $DASHSCOPE_API_KEY",
    "Content-Type": "application/json"
}

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

### Create Feature View - curl - all

```curl
curl -X POST 'https://api.aliyun.com/api/PaiFeatureStore/2023-06-21/CreateFeatureView' \
-H 'Authorization: Bearer <your-api-key>' \
-H 'Content-Type: application/json' \
-d '{"InstanceId":"fs-cn-********","body":{"ProjectId":"3","Name":"FeatureView1","Type":"Batch","WriteMethod":"Custom","SyncOnlineTable":true,"TTL":90,"Tags":["label1"],"Fields":[{"Name":"age","Type":"INT32","Attributes":["Partition"]}]}}'
```

### Query Online Features - curl - all

```curl
curl -X GET 'https://api.aliyun.com/api/PaiFeatureStore/2023-06-21/ListFeatureViewOnlineFeatures?InstanceId=fs-cn-********&FeatureViewId=1' \
-H 'Authorization: Bearer <your-api-key>'
```

### Create Feature Entity - curl - all

```curl
curl -X POST https://api.aliyun.com/api/PaiFeatureStore/2023-06-21/CreateFeatureEntity?InstanceId=fs-cn-******** \
-H "Authorization: Bearer <your-api-key>" \
-H "Content-Type: application/json" \
-d '{
  "JoinId": "user_id",
  "Name": "feature_entity_1",
  "ProjectId": "3",
  "ParentFeatureEntityId": "1"
}'
```

### Create Model Feature - curl - all

```curl
curl -X POST https://api.aliyun.com/api/PaiFeatureStore/2023-06-21/CreateModelFeature?InstanceId=fs-cn-******** \
-H "Authorization: Bearer <your-api-key>" \
-H "Content-Type: application/json" \
-d '{
  "ProjectId": "3",
  "Name": "model_feature_1",
  "LabelTableId": "4",
  "Features": [
    {
      "FeatureViewId": "5",
      "Name": "user_id",
      "AliasName": "userid",
      "Type": "STRING"
    }
  ],
  "SequenceFeatureViewIds": [],
  "LabelPriorityLevel": 0
}'
```

### Create Project - curl - all

```curl
curl -X POST https://api.aliyun.com/api/PaiFeatureStore/2023-06-21/CreateProject?InstanceId=fs-cn-******** \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "Name": "project1",
  "WorkspaceId": "324",
  "Description": "This is a test.",
  "OfflineDatasourceId": "4",
  "OfflineLifeCycle": 90,
  "OnlineDatasourceId": "3"
}'
```

### Get Task Details - python - all

```python
import requests

url = "https://api.aliyun.com/api/PaiFeatureStore/2023-06-21/GetTask"
params = {
    "InstanceId": "fs-cn-********",
    "TaskId": "3"
}
headers = {
    "Authorization": "Bearer $DASHSCOPE_API_KEY",
    "Content-Type": "application/json"
}

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

## Response Format

```json
{
  "RequestId": "1C5B1511-8A5B-59C3-90AF-513F9210E882",
  "DatasourceId": "3"
}
```

**Key Fields**:
- `RequestId` — Unique identifier for the API request, useful for troubleshooting
- `DatasourceId` — The ID of the created or retrieved datasource
- `FeatureViewId` — The ID of the created or retrieved feature view
- `FeatureEntityId` — The ID of the created or retrieved feature entity
- `LabelTableId` — The ID of the created or retrieved label table
- `ModelFeatureId` — The ID of the created or retrieved model feature
- `ProjectId` — The ID of the created or retrieved project
- `TaskId` — The ID of the created or retrieved task

## Error Handling

| Error Code (Code) | Description (Description) | Recommended Action (Recommended Action) |
|---------------|--------------------|-----------------------------|
| 400 | Bad Request - The request parameters are invalid or missing. | Verify that all required parameters are provided and formatted correctly according to the API specification. |
| 403 | Forbidden - The user does not have sufficient permissions to perform this operation. | Check your RAM role permissions and ensure you have the required featurestore:* permissions for the operation. |
| 404 | Not Found - The specified instance or workspace does not exist. | Verify the InstanceId, WorkspaceId, and other resource IDs using the appropriate List* operations. |
| 500 | Internal Server Error - An unexpected error occurred on the server side. | Retry the request after a short delay. If the issue persists, contact Alibaba Cloud support with the RequestId. |
| InvalidParameter | One or more parameters are invalid. Check that InstanceId, DatasourceId, and TableName are correctly formatted and valid. | Validate parameter values against the constraints specified in the API documentation. |
| ResourceNotFound | The specified resource (instance, data source, or table) does not exist. Verify the IDs and ensure they are correct and accessible. | Use List* operations to confirm the existence of resources before referencing them. |
| UnauthorizedOperation | You do not have permission to access this resource. Ensure your RAM role or API key has the required permissions (featurestore:GetDatasourceTable). | Update your RAM policy to include the necessary featurestore permissions for your use case. |
| DependencyExists | The feature view is referenced by a model feature and cannot be deleted until the dependent model feature is removed. | First delete or update the dependent model features before attempting to delete the feature view. |
| Throttling | The request rate exceeds the allowed limit. Please reduce the number of requests. | Implement exponential backoff retry logic and respect the QPS limits specified in the documentation. |

## Environment Requirements

- **Environment variable setup**: `export DASHSCOPE_API_KEY=your_api_key_here`
- **Python SDK**: For Python examples using the feature store client, install: `pip install feature-store-py>=1.0.0`

## FAQ

Q: How do I authenticate with the Feature Store API?
A: Use Bearer Token authentication by setting the `DASHSCOPE_API_KEY` environment variable and including the header `Authorization: Bearer $DASHSCOPE_API_KEY` in all API requests.

Q: What data sources are supported by the Feature Store?
A: The Feature Store supports Hologres, GraphCompute, Redis, MaxCompute, and FeatureDB as data sources for both offline and online feature storage.

Q: How do I query online features in real-time?
A: Use the ListFeatureViewOnlineFeatures API with the InstanceId, FeatureViewId, and JoinIds parameters to retrieve feature values for specific entities in real-time.

Q: What is the difference between Batch and Stream feature views?
A: Batch feature views are used for offline features that are computed periodically, while Stream feature views handle real-time features that are updated continuously as new events arrive.

Q: How do I handle asynchronous operations like data imports?
A: For asynchronous operations, the API returns a TaskId immediately. Use the GetTask API with this TaskId to monitor the task status until completion.

## Pricing & Billing

### Billing Model
All Feature Store APIs use a per-request billing model where each API call is charged regardless of success or failure.

### Price Reference

| Tier/Model | Input Price | Output Price | Other Fees |
|-----------|---------|---------|---------|
| default | 0.001 / | 0.001 / |
| standard | 0.0001 / | 0.0001 / |

### Free Tier
Most operations include a monthly free tier ranging from 100 to 10,000 free calls per month, depending on the specific API operation.

### Usage Limits
- QPS limits range from 10 to 100 requests per second per account
- Single request size limits up to 8K tokens or 8KB
- Pagination limits of 100 items per page for list operations

### Billing Notes
- Each API call is counted as one request regardless of the response size or data volume returned
- Failed requests are also billed and count toward your quota
- Free tier quotas reset monthly and do not roll over to subsequent months