Reading Online Features for Inference Using the HTTP API
Using the HTTP API is the recommended way to read features for inference. The HTTP API provides reads at low latency.
Creating an API key to authenticate to the HTTP API​
To authenticate your requests to the HTTP API, you will need to create a Service Account to obtain an API key, and grant that Service Account the Consumer role for your workspace:
- Create the Service Account to obtain your API key.
tecton service-account create \
--name "sample-service-acount" \
--description "An online inference sample"
Output:
Save this API Key - you will not be able to get it again.
API Key: <Your-api-key>
Service Account ID: <Your-Service-Account-Id>
- Assign the Consumer role to your Service Account.
tecton access-control assign-role --role consumer \
--workspace <Your-workspace> \
--service-account <Your-Service-Account-Id>
Output:
Successfully updated role.
- Export the API key as an environment variable named
TECTON_API_KEY
or add the key to your secret manager.
export TECTON_API_KEY="<Your-api-key>"
Making an HTTP API call using the get-features
endpoint​
In a prediction service application, make the HTTP API call from the service's HTTP client. The following example uses cURL as the HTTP client and can be executed from the command line, but the HTTP call is the same for any client.
To request a single feature vector from the HTTP API, use the get-features
endpoint. Pass the Feature Service name and the join keys as parameters. The
response is a JSON object.
Example Request
$ curl -X POST https://<your_cluster>.tecton.ai/api/v1/feature-service/get-features\
-H "Authorization: Tecton-key $TECTON_API_KEY" -d\
'{
"params": {
"workspace_name": "prod",
"feature_service_name": "fraud_detection_feature_service",
"join_key_map": {
"user_id": "C1000262126"
},
"request_context_map": {
"amount": 100
}
}
}'
Response
{
"result": {
"features": ["0", "1", 216409]
}
}
Metadata options for the HTTP API​
You can specify metadata_options
to get additional relevant information about
your feature vector.
include_names
: the name of each feature in the vectorinclude_effective_times
: timestamp of the most recent feature value that was written to the online storeinclude_data_types
: the data types of each feature in the vectorinclude_slo_info
: information about the server response timeinclude_serving_status
: return feature status information about the feature. Options available are listed:PRESENT
: The feature values were found in the online store for the join keys requested.MISSING_DATA
: The feature values were not found in the online store either because the join keys do not exist or the feature values are outside ttl.UNKNOWN
: An unknown status code occurred, most likely because an error occurred during feature retrieval.
Example Request
$ curl -X POST https://<your_cluster>.tecton.ai/api/v1/feature-service/get-features\
-H "Authorization: Tecton-key $TECTON_API_KEY" -d\
'{
"params": {
"workspace_name": "prod",
"feature_service_name": "fraud_detection_feature_service",
"join_key_map": {
"user_id": "C1000262126"
},
"request_context_map": {
"amount": 100
},
"metadata_options": {
"include_names": true,
"include_effective_times": true,
"include_data_types": true,
"include_slo_info": true,
"include_serving_status": true
}
}
}'
Example Response
{
"result": {
"features": ["0", "1", 216409]
},
"metadata": {
"features": [
{
"name": "transaction_amount_is_high.transaction_amount_is_high",
"dataType": {
"type": "int64"
},
"status": "PRESENT"
},
{
"name": "transaction_amount_is_higher_than_average.transaction_amount_is_higher_than_average",
"dataType": {
"type": "int64"
},
"status": "PRESENT"
},
{
"name": "last_transaction_amount_sql.amount",
"effectiveTime": "2021-08-21T01:23:58.996Z",
"dataType": {
"type": "float64"
},
"status": "PRESENT"
}
],
"sloInfo": {
"sloEligible": true,
"sloServerTimeSeconds": 0.039343822,
"dynamodbResponseSizeBytes": 204,
"serverTimeSeconds": 0.049082851
}
}
}
The top-level dataType.type
field may be one of boolean
, int64
, string
,
float64
, or array
.
Arrays support int64
, string
, float64
, and float32
element types, which
are represented like:
"dataType": {
"type": "array",
"elementType": {
"type": "float32"
}
}
Tecton represents double
feature values as JSON numbers and int64
feature
values as JSON strings.
This is because JSON does not specify a precision for numerical values, and most
JSON libraries treat all numerical values as double-precision floating point
numbers. Representing int64
values as double-precision floating point numbers
is problematic because not all values can be represented exactly.
As a result, Tecton serializes int64
values in the response body as strings,
which can be seen in the example response above. It is recommended to parse the
string as a signed 64 bit integer in your client application to maintain full
precision.
Feature ordering in a Feature Service​
You can determine the ordering of features in a feature service by setting the
include_names
field in your request metadata. The feature ordering will be in
the metadata.features
. This ordering is stable; it will remain the same for
each call.
"metadata_options": {
"include_names": true
}
The ordering is determined with the following rules:
- Within on-demand feature views, features ordering is the same as output_schema
- Within all other feature views, features ordering is alphabetical.
- Requests that return multiple feature views place on-demand features first (in alphabetical order) followed by the others (in alphabetical order).
Making an HTTP API call in Python using the get-features
endpoint​
You can wrap this HTTP request using your favorite library such as requests
Example Request
data = {
"params": {
"workspace_name": "prod",
"feature_service_name": "fraud_detection_feature_service",
"join_key_map": {
"user_id": "C1000262126",
},
"request_context_map": {"amount": 100},
}
}
headers = {"Authorization": f"Tecton-key {TECTON_API_KEY}"}
r = requests.post(
"https://<your-cluster>.tecton.ai/api/v1/feature-service/get-features",
data=json.dumps(data),
headers=headers,
)
print(json.dumps(r.json(), indent=4, sort_keys=True))
HTTP API Reference​
The HTTP API Reference can be found here.