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

An HTTP API request is authenticated using an API key, which a Service Account contains.

Create an API key with the CLI by running the following command. This command also creates a Service Account containing the API key. The Service Account is created on the Tecton instance that you are logged into.

tecton api-key create --description "A sample key for the documentation"

Go to the Permissions screen for your workspace and add your new Service Account to the workspace. Then grant the Consumer, Editor, or Owner role to the Service Account.

Finally, 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 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 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
• include_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
    }
  }
}'

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"
    }
}

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.

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:

1. Within on-demand feature views, features ordering is the same as output_schema
2. Within all other feature views, features ordering is alphabetical.
3. 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.