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()

See the API reference for details.

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 vector
include_effective_times: timestamp of the most recent feature value that was written to the online store
include_data_types: the data types of each feature in the vector
include_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.