Read 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:

1. 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>

2. 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.

3. 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": {
    "workspaceName": "prod",
    "featureServiceName": "fraud_detection_feature_service",
    "joinKeyMap": {
      "user_id": "C1000262126"
    },
    "requestContextMap": {
      "amount": 100
    }
  }
}'

Response

{
  "result": {
    "features": ["0", "1", 216409]
  }
}

Metadata options for the HTTP API

You can specify metadataOptions to get additional relevant information about your feature vector.

• includeNames: the name of each feature in the vector
• includeEffectiveTimes: timestamp of the most recent feature value that was written to the online store
• includeDataTypes: the data types of each feature in the vector
• includeSloInfo: information about the server response time
• includeServingStatus: 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": {
    "workspaceName": "prod",
    "featureServiceName": "fraud_detection_feature_service",
    "joinKeyMap": {
      "user_id": "C1000262126"
    },
    "requestContextMap": {
      "amount": 100
    },
    "metadataOptions": {
      "includeNames": true,
      "includeEffectiveTimes": true,
      "includeDataTypes": true,
      "includeSloInfo": true,
      "includeServingStatus": 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.

Special FLOAT64 Value

JSON can't represent Infinity, -Infinity and NaN as a number value. In request, you can use the following strings to represent these values respectively: "Infinity", "-Infinity" and "NaN". In the response, Tecton sends these strings if your feature value is one of them.

Feature ordering in a Feature Service

You can determine the ordering of features in a feature service by setting the includeNames 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.

"metadataOptions": {
    "includeNames": 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": {
        "workspaceName": "prod",
        "featureServiceName": "fraud_detection_feature_service",
        "joinKeyMap": {
            "user_id": "C1000262126",
        },
        "requestContextMap": {"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.