Fetching Online Features
This guide will show you how to retrieve a feature vector from the online store. This feature vector can then be used for inference in your production model.
We assume you've already created a Feature View and added it to a Feature Service, as shown in the prior guides.
Background
A model prediction service needs feature vectors delivered as input with low latency. Tecton makes pre-computed, or materialized, features available for low-latency retrieval.
You might also need to calculate features from raw data at request-time. For online features that can only be calculated at request time, use an OnDemandFeatureView.
Tecton recommends using the HTTP API to fetch feature values in production. Additionally, the Python SDK offers convenient methods for testing feature retrieval. Examples for both are shown below.
Fetching Online Features with the Python SDK
Authenticating with an API key
If you're using an EMR or Databricks notebook that has been configured to work with Tecton, you can skip this section as the API key is already configured.
Otherwise you'll need to set an API key to authenticate these requests.
First, use the CLI to create a key.
tecton api-key create --description "A sample key for the documentation".
Then set the API key in the SDK.
import tecton
tecton.conf.set("TECTON_API_KEY", "my-key-code")
Using the FeatureService.get_online_features()
method
To fetch online features from a Feature Service containing both OnDemand Feature Views and materialized Feature Views, provide both join_keys
and request_data
as inputs. If your Feature Service only includes materialized Feature Views then you can omit the request_data
input, and vice-versa.
import tecton
my_fs = tecton.get_feature_service('fraud_detection_feature_service')
keys = {
"user_id": "C1000262126"
}
request_data = {
"amount" : 100
}
response = my_fs.get_online_features(join_keys=keys, request_data=request_data)
response.to_dict()
Using the low-latency REST API Interface
Authenticating with an API Key
Generate an API key from your CLI by running the following command:
tecton api-key create --description "A sample key for the documentation".
Then, export the API key as an environment variable named TECTON_API_KEY
or add the key to your secret manager.
export TECTON_API_KEY="my-key-code"
Making an HTTP API Call
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 REST 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 REST 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 time
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
}
}
}'
Example Response
{
"result": {
"features": [
"0",
"1",
216409,
]
},
"metadata": {
"features": [
{
"name": "transaction_amount_is_high.transaction_amount_is_high",
"data_type": {
"type": "int64"
}
},
{
"name": "transaction_amount_is_higher_than_average.transaction_amount_is_higher_than_average",
"data_type": {
"type": "int64"
}
},
{
"name": "last_transaction_amount_sql.amount",
"effectiveTime": "2021-08-21T01:23:58.996Z",
"dataType": {
"type": "float64"
}
}
],
"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"
}
}
JSON Value Representations
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.