Chalk Clients

Chalk maintains several client libraries (gRPC) and a REST API for fetching feature values.

​

Library support

Chalk maintains libraries in several major languages for fetching online feature values. If you need support for a language that we don’t support, let us know! We also support a rest API if you’d like to build your own.

1
2
3
4
5
6
7
8
> chalk query \
      --in user.id=1 \
      --out user.identity.is_voip_phone \
      --out user.fraud_score \
      --staleness user.account_balance=10m \
      --environment staging \
      --tag live

​

REST API

Chalk supports a REST API for querying online features and exposes this endpoint in several API clients. When you execute an online query, resolvers will execute to produce the requested data. Online query will prioritize running online resolvers over offline resolvers to compute features if both are possible.

The following endpoint can also be hit with the python ChalkClient by using its query method. For information on how to authenticate the ChalkClient, check out the section on authentication. Read more about the parameters to this method here.

​

Request

More information on parameters is available here

​

Response

​

Query Explanation

Chalk offers support for the user for when queries don’t work. The first step is always to check to see the response contains any errors. Often, the error message will directly point to the failure.

In the case of more complicated queries, queries can be sent with explain=True. This will return a representation of the query plan in the meta return attribute. The user can use this information to verify the resolvers and operators ran during execution. Beware, this will result in slower execution times.

Some queries that involve multiple operations might need additional tracking. Users can supply store_plan_stages=True to store intermediate outputs at all operations of the query. This will dramatically slow things down, so use wisely! These results are visible in the dashboard under the “Queries” page.

For more information, read the ChalkClient docs here.

​

Online Query Bulk

Compute feature values for many rows of inputs using online resolvers. This endpoint is similar to the online query endpoint, but takes in lists of inputs and produces one output per row of inputs. This is appropriate when you want to fetch the same set of features for many different input primary keys.

The following endpoint can be accessed with the Python ChalkClient by using its query_bulk method.

​

Request

The request body should be a binary payload containing:

1. A magic string identifier
2. Serialized query metadata
3. Feature data in Apache Feather format

When using the ChalkClient, this serialization is handled automatically. For direct HTTP usage, the structure is:

• Request inputs are provided as mappings of feature names to lists of values
• Each list should have the same length, representing multiple rows of data

{
  "user.id": [1, 2],
  "user.name": ["Alice", "Bob"],
  "user.profile": [
    {"age": 30, "city": "NYC"},
    {"age": 25, "city": "SF"}
  ],
  "user.cards": [
    [{"id": "card1"}, {"id": "card2"}],
    [{"id": "card3"}]
  ]
}

​

Response

The response is a binary payload in Apache Feather format containing the results.

​

Offline Query

Submit an offline query to compute feature values from the offline store or by running offline/online resolvers. Offline queries are typically used for generating training datasets and run asynchronously.

The following endpoint can be accessed with the Python ChalkClient by using its offline_query method. See the offline query documentation for more information.

​

Request

The request body is a binary payload containing:

1. Serialized query plan (protobuf)
2. Query metadata (JSON)
3. Input data (Apache Feather format)

When using the ChalkClient, this serialization is handled automatically.

​

Response

The response contains information about the submitted offline query job.

​

Check Offline Query Status

Check the status of an offline query job. Offline queries run asynchronously, so you need to poll this endpoint to determine when the job is complete and the results are ready.

​

Request

You must provide at least one of: job_id, dataset_name, or dataset_id.

​

Response

Once is_finished is true, you can download the data from the provided URLs and load it into a DataFrame. The ChalkClient’s Dataset object handles this automatically.