chalk

package module
v1.2.74 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 19, 2025 License: Apache-2.0 Imports: 34 Imported by: 1

README

Go Reference Test

Go Chalk

The official Chalk client library.

Usage

Requirements
  • Go 1.19 or later
Installation

Make sure your project is using Go Modules (it will have a go.mod file in its root if it already is):

go mod init

Then, reference chalk-go in a Go program with import:

import (
    "github.com/chalk-ai/chalk-go"
)

Run any of the normal go commands (build/install/test). The Go toolchain will resolve and fetch the chalk-go module automatically.

Alternatively, you can also explicitly go get the package into a project:

go get -u github.com/chalk-ai/chalk-go
Codegen

Chalk generates Go structs from your python feature definitions, which makes it easy to use your features from Go.

Run the code-gen command inside your chalk project to generate a file containing your generated structs, then copy that file into your go project.

chalk codegen go --out=<OUTPUT_FILEPATH>
Connect to chalk

Create a client using the NewClient method. The returned client gets its configuration:

  1. From overrides configured by passing in a *chalk.ClientConfig
  2. From environment variables if no arguments are passed
  3. From a ~/.chalk.yml file if neither 1 nor 2 are available

(2) and (3) are applicable only for these options.

Without overrides
import (
    "github.com/chalk-ai/chalk-go"
)

client := chalk.NewClient(context.Background())
With overrides
client, err := chalk.NewClient(
	context.Background(),
	&chalk.ClientConfig{
		ClientId:      "id-89140a6614886982a6782106759e30",
		ClientSecret:  "sec-b1ba98e658d7ada4ff4c7464fb0fcee65fe2cbd86b3dd34141e16f6314267b7b",
		ApiServer:     "https://api.chalk.ai",
		EnvironmentId: "qa",
		Branch:        "jorges-december",
	}
)
gRPC Client

To use gRPC as the underlying protocol for communication with Chalk:

// Create a client
client, err := chalk.NewGRPCClient(
	context.Background(),
	&chalk.GRPCClientConfig{Branch: "my-branch"},
)

// Online query
var users []User
res, err := chalk.OnlineQueryBulk(
	context.Background(),
	chalk.OnlineQueryParams{}.
		WithInput(Features.User.Id, []string{"u273489056"}).
		WithInput(Features.User.Transactions, [][]Transaction{
			{
				{Id: utils.ToPtr("txn8f76"), Amount: utils.ToPtr(13.23)},
				{Id: utils.ToPtr("txn546d"), Amount: utils.ToPtr(48.95)},
			},
		}).
		WithOutputs(Features.User.Id, Features.User.WeightedScore),
)
if err != nil {
	return errors.Wrap(err, "querying weighted score")
}
if err = res.UnmarshalInto(&users); err != nil {
	return errors.Wrap(err, "unmarshalling into users")
}
fmt.Println("user %s has weighted score %v", users[0].Id, users[0].WeightedScore)


// Multi-namespace online query
type underwriting struct {
	User 
	Loan  
}

res, err := chalk.OnlineQueryBulk(
    context.Background(),
    chalk.OnlineQueryParams{}.
        WithInput(Features.User.Id, []string{"u273489056"}).
        WithInput(Features.Loan.Id, []string{"l273489056"}).
        WithOutputs(
            Features.User.Id, 
            Features.User.WeightedScore, 
            Features.Loan.Id, 
            Features.Loan.ApprovalStatus,
        ),
)
if err != nil {
	return errors.Wrap(err, "querying weighted score and loan approval status")
}

var root []underwriting
if err = res.UnmarshalInto(&root); err != nil {
	return errors.Wrap(err, "unmarshalling into underwriting")
}
fmt.Println("user %s has weighted score %v", root[0].User.Id, root[0].User.WeightedScore)
fmt.Println("loan %s has approval status %v", root[0].Loan.Id, root[0].Loan.ApprovalStatus)
Online Query

Query online features using the generated feature structs. Access the results in the returned object or by passing the address of a variable with the correct type.

user := User{}
_, err = client.OnlineQuery(
    context.Background(),
    chalk.OnlineQueryParams{}.
        WithInput(Features.User.Id, "u273489057").
        WithInput(Features.User.Transactions, []Transaction{
            {Id: utils.ToPtr("sd8f76"), Amount: utils.ToPtr(13.23)},
            {Id: utils.ToPtr("jk546d"), SeriesId: utils.ToPtr(48.95)},
        }).
        WithOutputs(Features.User.Id, Features.User.LastName),
    &user,
)
Named Queries

If your deployment contains named queries, you can specify a query name instead of outputs when making a query.

user := User{}
_, err = client.OnlineQuery(
    context.Background(),
    chalk.OnlineQueryParams{}.
        WithInput(Features.User.Id, "u273489057").
        WithQueryName("user_underwriting_features"),
    &user,
)
Offline Query

When executing an offline query, a dataset is returned and can be downloaded as parquet files using the DownloadData method.

res, _ := client.OfflineQuery(
    context.Background(),
    chalk.OfflineQueryParams{}.
        WithInput(Features.User.Id, []any{...}).
        WithOutputs(Features.User),
)

err = res.Revisions[0].DownloadData(<FILE_DIRECTORY>)
Upload Features

Chalk allows you to synchronously persist features directly to your online and offline stores.

res, err := client.UploadFeatures(
    context.Background(), 
    chalk.UploadFeaturesParams{
        Inputs: map[any]any{
            Features.User.Id: []string{"user-1", "user-2"},
            "user.last_name": []string{"Borges", "Paris"},
        },
    },
)
Update Aggregates

Note: This method is available only when using the gRPC client. See gRPC Client for more information.

You can easily update your windowed aggregation feature values with UpdateAggregates. For example, with this feature definition:

@features
class User:
    id: str
    txns: "DataFrame[Transaction]"
    txn_amount_total: Windowed[int] = windowed(
        "30d",
        "90d",
        materialization={
            "bucket_duration": "1d",
        },
        expression=_.txns[_.amount].sum(),
    )

@features
class Transaction:
    id: Primary[str]
    amount: float
    user_id: str

Then to update the txn_amount_total feature, you would upload features corresponding to that aggregation:

res, err := client.UpdateAggregates(
    context.Background(),
    chalk.UpdateAggregatesParams{
        Inputs: map[any]any{
            "transaction.id": []string{"txn-1", "txn-2"},
            "transaction.user_id": []string{"user-1", "user-2"},
            "transaction.amount": []float64{100.0, 200.0},
            "transaction.__chalk_observed_at__": []time.Time{time.Now(), time.Now()},
        },
    },
)

Note that if you have an explicit FeatureTime feature specified, you could provide that in place of the __chalk_observed_at__ column.

Querying against a branch

To query against a branch, create a ChalkClient with a Branch specified, and then make queries using that client.

client, err := chalk.NewClient(
	context.Background(),
	&chalk.ClientConfig{
		Branch:        "jorges-december",
	},
)
Configuring Logging

By default, Chalk logs error messages only (which are sent to stderr). Configure default logging using the global DefaultLeveledLogger variable:

chalk.DefaultLeveledLogger = &chalk.StdOutLeveledLogger{
    Level: chalk.LevelInfo,
}

It's possible to use non-Chalk leveled loggers as well. Chalk expects loggers to comply to the following interface:

type LeveledLogger interface {
    Debugf(format string, v ...interface{})
    Errorf(format string, v ...interface{})
    Infof(format string, v ...interface{})
    Warnf(format string, v ...interface{})
}

Some loggers like Logrus and Zap's SugaredLogger support this interface natively, so it's possible to set DefaultLeveledLogger to a *logrus.Logger or *zap.SugaredLogger directly. To use other loggers, you may need a shim layer.

Contributing

We'd love to accept your patches! If you submit a pull request, please keep the following guidelines in mind:

  1. Fork the repo, develop and test your code changes.
  2. Ensure your code adheres to the existing style.
  3. Ensure that your code has an appropriate set of tests that pass.
  4. Submit a pull request.
Development

Clone the git repo from github.com/chalk-ai/chalk-go.

  1. All patches must be go fmt compatible.
  2. All types, structs, and functions should be documented.
Testing

To execute the tests: go test ./.... Enure all tests pass

License

Apache 2.0 - See LICENSE for more information.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// Request errors are raised before execution of your
	// resolver code. They may occur due to invalid feature
	// names in the input or a request that cannot be satisfied
	// by the resolvers you have defined.
	Request = ErrorCodeCategory{"REQUEST"}

	// Field errors are raised while running a feature resolver
	// for a particular field. For this type of error, you'll
	// find a feature and resolver attribute in the error type.
	// When a feature resolver crashes, you will receive null
	// value in the response. To differentiate from a resolver
	// returning a null value and a failure in the resolver,
	// you need to check the error schema.
	Field = ErrorCodeCategory{"FIELD"}

	// Network errors are thrown outside your resolvers.
	// For example, your request was unauthenticated,
	// connection failed, or an error occurred within Chalk.
	Network = ErrorCodeCategory{"NETWORK"}
)
View Source 
var (
	// ParseFailed indicates the query contained features that do not exist.
	ParseFailed = ErrorCode{Value: "PARSE_FAILED"}

	// ResolverNotFound indicates a resolver was required as part of running the dependency graph that could not be found.
	ResolverNotFound = ErrorCode{"RESOLVER_NOT_FOUND"}

	// InvalidQuery indicates the query is invalid. All supplied features need to be rooted in the same top-level entity.
	InvalidQuery = ErrorCode{"INVALID_QUERY"}

	// ValidationFailed indicates a feature value did not match the expected schema (e.g. `incompatible type "int"; expected "str"`)
	ValidationFailed = ErrorCode{"VALIDATION_FAILED"}

	// ResolverFailed indicates the resolver for a feature errored.
	ResolverFailed = ErrorCode{"RESOLVER_FAILED"}

	// ResolverTimedOut indicates the resolver for a feature timed out.
	ResolverTimedOut = ErrorCode{"RESOLVER_TIMED_OUT"}

	// UpstreamFailed indicates a crash in a resolver that was to produce an input for the resolver crashed, and so the resolver could not run.
	UpstreamFailed = ErrorCode{"UPSTREAM_FAILED"}

	// Unauthenticated indicates the request was submitted with an invalid authentication header.
	Unauthenticated = ErrorCode{"UNAUTHENTICATED"}

	// Unauthorized indicates the supplied credentials do not provide the right authorization to execute the request.
	Unauthorized = ErrorCode{"UNAUTHORIZED"}

	// InternalServerError indicates an unspecified error occurred.
	InternalServerError = ErrorCode{"INTERNAL_SERVER_ERROR"}

	// Cancelled indicates the operation was cancelled, typically by the caller.
	Cancelled = ErrorCode{"CANCELLED"}

	// DeadlineExceeded indicates the deadline expired before the operation could complete.
	DeadlineExceeded = ErrorCode{"DEADLINE_EXCEEDED"}
)
View Source 
var (
	HeaderKeyDeploymentType = "x-chalk-deployment-type"
	HeaderKeyEnvironmentId  = "x-chalk-env-id"
	HeaderKeyServerType     = "x-chalk-server"
	HeaderKeyDeploymentTag  = "x-chalk-deployment-tag"
	HeaderKeyResourceGroup  = "x-chalk-resource-group"
)

Functions

func ConvertTableToRows added in v0.16.21 

func ConvertTableToRows(table arrow.Table) ([]map[string]any, error)

func DesuffixFqn 

func DesuffixFqn(fqn string) string

func InitFeatures 

func InitFeatures[T any](t *T) error

func SnakeCase added in v0.8.2 

func SnakeCase(s string) string

func UnmarshalInto added in v0.3.6 

func UnmarshalInto(resultHolder any, fqnToValue map[Fqn]any) (returnErr error)

UnmarshalInto unmarshals a map with keys being FQNs and values being the value for a singular feature (rather than a list of values for multiple pkeys) into a struct whose fields correspond to the FQNs. An illustration: 

type FinancialMetric struct {
	Id *string
	BusinessId *string
	MetricDate *time.Time
}

func main() {
	fqnToValue := map[Fqn]any{
		"FinancialMetric.Id": "id1",
		"FinancialMetric.BusinessId": "business_id1",
		"FinancialMetric.MetricDate": time.Now(),
	}
	fm := FinancialMetric{}
	if err := UnmarshalInto(&fm, fqnToValue); err != nil {
		fmt.Println(err)
	} else {
		fmt.Println(fm)
	}
}

To ensure fast unmarshals, see `WarmUpUnmarshaller`.

func UnmarshalTableInto added in v0.7.0 

func UnmarshalTableInto(table arrow.Table, resultHolders any) error

UnmarshalTableInto unmarshals the given Arrow table into the given result holders. The result holders should be a pointer to a slice of structs.

Usage: 

func printNumRelatives(chalkClient chalk.Client) {
	result, _ := chalkClient.OnlineQueryBulk(
	    context.Background(),
	    chalk.OnlineQueryParams{}.WithOutputs(
		    Features.User.Relatives,
	    ).WithInput(Features.User.Id, []int{1, 2}),
	    nil
	)

	relatives := make([]Relative, 0)
	result.UnmarshalInto(&relatives)

	feature, _ := chalk.UnwrapFeature(Features.User.Relatives)
	fmt.Println("Number of relatives for all users: ", len(result.GroupsTable[feature.Fqn]))

}

func WarmUpUnmarshaller added in v0.22.0 

func WarmUpUnmarshaller[T any](featureStruct *T) error

WarmUpUnmarshaller builds a memo to make unmarshalling efficient. This function should be called only once * at init time, instead of per query. If this function is not called, the first query will be slower, but * subsequent queries that unmarshals into the same structs will be faster because they will use the memo built * implicitly by the first query. * * This function takes in either an anonymous struct that contains all feature structs, or an individual * feature struct. It also recursively builds memos for all nested feature structs. * * Example usage: * type User struct { * Id *string * Transactions *[]Transactions `has_many:"id,user_id"` * Grade *int `versioned:"default(2)"` * GradeV1 *int `versioned:"true"` * GradeV2 *int `versioned:"true"` * } * type Transactions struct { * Id *string * UserId *string * Amount *float64 * } * var Features struct { * User *User * Transactions *Transactions * } * func init() { * if err := chalk.WarmUpUnmarshaller(&Features); err != nil { * panic("error initializing unmarshalling") * } * }

Types

type BatchReport added in v1.2.70 

type BatchReport struct {
	OperationID       string             `json:"operation_id"`
	Status            string             `json:"status"`
	EnvironmentID     string             `json:"environment_id"`
	TeamID            string             `json:"team_id"`
	DeploymentID      string             `json:"deployment_id"`
	Error             *ServerError       `json:"error,omitempty"`
	GeneratedAt       string             `json:"generated_at"`
	AllErrors         []ServerError      `json:"all_errors,omitempty"`
	OperationMetadata *map[string]string `json:"operation_metadata,omitempty"`
	ComputerID        *int               `json:"computer_id,omitempty"`
}

BatchReport represents the status of a batch operation.

type BoolValue added in v0.20.2 

type BoolValue bool

func (BoolValue) ToProto added in v0.20.2 

func (v BoolValue) ToProto() (*structpb.Value, error)

type Client 

type Client interface {
	// OnlineQuery computes features values using online resolvers.
	// See [query basics] for more information.
	//
	// resultHolder is a pointer to the struct that the result should be
	// unmarshalled into. The struct passed in should be the struct that
	// represents the feature set corresponding to the root output namespace.
	// For instance, in the example below, 'user' is the root output
	// namespace, so a pointer to a 'User' struct is passed in.
	// You can also choose to pass 'nil' as the resultHolder, in which case
	// you should use OnlineQueryResult.UnmarshalInto to populate a struct.
	//
	// The Chalk CLI can codegen structs for all available features with
	// the [chalk codegen] command.
	//
	// Example:
	//
	//		user := User{}
	//		res, err := client.OnlineQuery(
	//			context.Background(),
	//			OnlineQueryParams{
	//				IncludeMeta: true,
	//				EnvironmentId: "pipkjlfc3gtmn",
	//			}.
	//			WithInput(Features.User.Card.Id, 4).
	//			WithOutputs(Features.User.Email, Features.User.Card.Id),
	//			&user,
	//		)
	//		fmt.Println("User email: ", user.Email)
	//		fmt.Println("User card ID: ", user.Card.Id)
	//
	// [chalk codegen]: https://docs.chalk.ai/cli#codegen
	// [query basics]: https://docs.chalk.ai/docs/query-basics
	OnlineQuery(ctx context.Context, args OnlineQueryParamsComplete, resultHolder any) (OnlineQueryResult, error)

	// OnlineQueryBulk computes features values using online resolvers,
	// and has the ability to query multiple primary keys at once.
	// OnlineQueryBulk also has the ability to return a has-many feature
	// in the form of an arrow.Record. The usual features are returned
	// in bulk in an arrow.Record too, with each column name corresponding
	// to the feature name.
	//
	// The Chalk CLI can codegen structs for all available features with
	// the [chalk codegen] command.
	//
	// Example:
	//
	// import "github.com/apache/arrow/go/v16/arrow/array"
	//
	//
	//		res, err := client.OnlineQueryBulk(
	//			context.Background(),
	//			OnlineQueryParams{
	//				IncludeMeta: true,
	//				EnvironmentId: "pipkjlfc3gtmn",
	//			}.
	//			WithInput("user.id", []int{1, 2, 3, 4}).
	//			WithOutputs("user.email", "user.transactions"),
	//		)
	//		defer res.Release()
	//
	//		reader := array.NewTableReader(res.ScalarsTable, 10_000)
	//		defer reader.Release()
	//		for reader.Next() {
	//		    record := reader.Record()
	//		    // Do something with the record
	//		}
	//
	//		txnTable := res.GroupsTables["user.transactions"]
	//		txnReader := array.NewTableReader(txnTable, 10_000)
	//		// Do something with the txnReader
	//		defer txnReader.Release()
	//
	// [chalk codegen]: https://docs.chalk.ai/cli#codegen
	// [query basics]: https://docs.chalk.ai/docs/query-basics
	OnlineQueryBulk(ctx context.Context, args OnlineQueryParamsComplete) (OnlineQueryBulkResult, error)

	// UploadFeatures synchronously persists feature values to the online store and
	// offline store. The `Inputs` parameter should be a map of features to values.
	// The features should either be a string or codegen-ed Feature object. The values
	// should be a slice of the appropriate type. All slices should be the same length
	// as the number of entities you want to upload features for.
	//
	// The upload is successful if the response contains no errors.
	//
	// Example:
	//
	// 		res, err := client.UploadFeatures(
	//			context.Background(),
	// 			UploadFeaturesParams{
	// 				Inputs: map[any]any{
	// 					Features.User.Card.Id: []string{"5555-5555-5555-5555", "4444-4444-4444-4444"},
	// 				    "new_user_model.card_id": []string{"5555-5555-5555-5555", "4444-4444-4444-4444"},
	//					"new_user_model.email": []string{"borges@chalk.ai", "jorge@chalk.ai"},
	// 				},
	//              BranchOverride: "jorge-december",
	// 			}
	// 		)
	//      if err != nil {
	//          return err.Error()
	//      }
	//
	// [chalk codegen]: https://docs.chalk.ai/cli#codegen
	UploadFeatures(ctx context.Context, args UploadFeaturesParams) (UploadFeaturesResult, error)

	// OfflineQuery queries feature values from the offline store.
	// See Dataset for more information.
	//
	// Example:
	//
	//		client.OfflineQuery(
	//			context.Background(),
	//			OfflineQueryParams{
	//				EnvironmentId: "pipkjlfc3gtmn",
	//			}.
	//	 		WithRequiredOutputs(Features.User.Email, Features.User.Card.Id),
	//		)
	//
	OfflineQuery(ctx context.Context, args OfflineQueryParamsComplete) (Dataset, error)

	// TriggerResolverRun triggers an offline resolver to run.
	// See https://docs.chalk.ai/docs/runs for more information.
	TriggerResolverRun(ctx context.Context, args TriggerResolverRunParams) (TriggerResolverRunResult, error)

	// GetRunStatus retrieves the status of an offline resolver run.
	// See https://docs.chalk.ai/docs/runs for more information.
	GetRunStatus(ctx context.Context, args GetRunStatusParams) (GetRunStatusResult, error)

	// GetToken retrieves a token that can be used to authenticate requests to the Chalk API
	// along with other using the client's credentials.
	GetToken(ctx context.Context) (*TokenResult, error)

	// GetOfflineQueryStatus retrieves the status of an offline query job.
	// See https://docs.chalk.ai/docs/query-basics for more information.
	GetOfflineQueryStatus(ctx context.Context, args GetOfflineQueryStatusParams) (GetOfflineQueryStatusResult, error)

	// GetDataset retrieves a dataset by its revision ID.
	// This allows you to access datasets that were created from previous offline queries.
	//
	// Example:
	//
	//		revisionId := "550e8400-e29b-41d4-a716-446655440000"
	//		dataset, err := client.GetDataset(context.Background(), revisionId)
	//		if err != nil {
	//			return err
	//		}
	//
	//		// Get download URIs for the dataset
	//		downloadUris, err := dataset.Revisions[0].DownloadUris(context.Background())
	//		if err != nil {
	//			return err
	//		}
	//
	//		for _, uri := range downloadUris {
	//			fmt.Println(uri)
	//		}
	//
	GetDataset(ctx context.Context, revisionId string) (Dataset, error)
}

Client is the primary interface for interacting with Chalk. You can use it to query data, trigger resolver runs, gather offline data, and more.

func NewClient 

func NewClient(ctx context.Context, configs ...*ClientConfig) (Client, error)

NewClient creates a Client with authentication settings configured. These settings can be overriden by passing in a ClientConfig object. Otherwise, for each configuration variable, NewClient uses its corresponding environment variable if it exists. The environment variables that NewClient looks for are: 

CHALK_ACTIVE_ENVIRONMENT
CHALK_API_SERVER
CHALK_CLIENT_ID
CHALK_CLIENT_SECRET

For each config variable, if it is still not found, NewClient will look for a `~/.chalk.yml` file, which is updated when you run chalk login. If a configuration for the specific project directory if found, that configuration will be used. Otherwise, the configuration under the key `default` will be used.

Example: 

     chalkClient, chalkClientErr := chalk.NewClient(
         context.Background(),
         &chalk.ClientConfig{
	         ClientId:      "id-89140a6614886982a6782106759e30",
	         ClientSecret:  "sec-b1ba98e658d7ada4ff4c7464fb0fcee65fe2cbd86b3dd34141e16f6314267b7b",
	         ApiServer:     "https://api.chalk.ai",
	         EnvironmentId: "qa",
	         Branch:        "jorges-december",
         },
     )

type ClientConfig 

type ClientConfig struct {
	ClientId      string
	ClientSecret  string
	ApiServer     string
	EnvironmentId string

	// If specified, Chalk will route all requests from this client
	// instance to the relevant branch.
	Branch string

	// Chalk can route queries to specific deployments using deployment
	// tags.
	DeploymentTag string

	// Chalk routes performance sensitive requests like online query
	// directly to the query server that runs the engine. Populate
	// this field if you would like to route these requests to a
	// different query server than the one automatically resolved
	// by Chalk.
	QueryServer string

	// Logger is the logger that the backend will use to log errors,
	// warnings, and informational messages.
	//
	// LeveledLogger is implemented by StdOutLeveledLogger, and one can be
	// initialized at the desired level of logging.  LeveledLogger
	// also provides out-of-the-box compatibility with a Logrus Logger, but may
	// require a thin shim for use with other logging libraries that use less
	// standard conventions like Zap.
	//
	// Defaults to DefaultLeveledLogger.
	//
	// To set a logger that logs nothing, set this to a chalk.LeveledLogger
	// with a Level of LevelNull (simply setting this field to nil will not
	// work).
	Logger LeveledLogger

	// HTTPClient is an HTTP client instance to use when making API requests.
	//
	// If left unset, it'll be set to a default HTTP client for the package.
	HTTPClient HTTPClient

	// ResourceGroup specifies the resource group to route all requests to. If set
	// on the request or query level, this will be overridden.
	ResourceGroup string

	// Timeout specifies the timeout for all requests. Defaults to no timeout.
	// Timeout of 0 means no timeout. Deadline or timeout set on the request
	// context overrides this timeout.
	Timeout time.Duration

	// Allocator specifies the allocator to use for creating Arrow objects.
	// Defaults to `memory.DefaultAllocator`.
	Allocator memory.Allocator
}

type ColumnMetadata 

type ColumnMetadata struct {
	FeatureFqn string `json:"feature_fqn"`
	ColumnName string `json:"column_name"`
	Dtype      string `json:"dtype"`
}

type Dataset 

type Dataset struct {
	// Whether the export job is finished (it runs asynchronously)
	IsFinished bool `json:"is_finished"`

	// Version number representing the format of the data. The client
	// uses this version number to properly decode and load the query
	// results into DataFrames.
	Version       int               `json:"version"`
	DatasetId     *string           `json:"dataset_id"`
	DatasetName   *string           `json:"dataset_name"`
	EnvironmentID string            `json:"environment_id"`
	Revisions     []DatasetRevision `json:"revisions"`
	Errors        serverErrorsT     `json:"errors"`
	// contains filtered or unexported fields
}

func (*Dataset) DownloadUris added in v1.2.71 

func (d *Dataset) DownloadUris(ctx context.Context) ([]string, error)

DownloadUris retrieves the download URIs for the dataset using the last revision. This method matches the Python client behavior where calling download_uris() on a Dataset automatically uses the last revision (self.revisions[-1]).

Example: 

dataset, err := client.GetDataset(context.Background(), revisionId)
if err != nil {
	return err
}

// This automatically uses the last revision
urls, err := dataset.DownloadUris(context.Background())
if err != nil {
	return err
}

for _, url := range urls {
	fmt.Println(url)
}

func (*Dataset) Wait added in v1.2.70 

func (d *Dataset) Wait(ctx context.Context) error

Wait polls the offline query status until the job is complete. It returns an error if the job fails or if there's an error polling the status. The method will continue polling until the job reaches a terminal state (COMPLETED or FAILED).

type DatasetFilter 

type DatasetFilter struct {
	SampleFilters DatasetSampleFilter `json:"sample_filters"`
	MaxCacheAge   *float64            `json:"max_cache_age_secs"`
}

type DatasetRevision 

type DatasetRevision struct {
	// UUID for the revision job.
	RevisionId string `json:"revision_id"`

	// UUID for the creator of the job.
	CreatorId string `json:"creator_id"`

	// Environment ID for the revision job.
	EnvironmentID string `json:"environment_id"`

	// Output features for the dataset revision.
	Outputs []string `json:"outputs"`

	// Location of the givens stored for the dataset.
	GivensUri *string `json:"givens_uri"`

	// Status of the revision job.
	Status QueryStatus `json:"status"`

	// Filters performed on the dataset.
	Filters DatasetFilter `json:"filters"`

	// Number of partitions for revision job.
	NumPartitions int `json:"num_partitions"`

	// Location of the outputs stored fo the dataset.
	OutputUris string `json:"output_uris"`

	// Storage version of the outputs.
	OutputVersion int `json:"output_version"`

	// Number of bytes of the output, updated upon success.
	NumBytes *int `json:"num_bytes"`

	// Timestamp for creation of revision job.
	CreatedAt *time.Time `json:"created_at"`

	// Timestamp for start of revision job.
	StartedAt *time.Time `json:"started_at"`

	// Timestamp for end of revision job.
	TerminatedAt *time.Time `json:"terminated_at"`

	// Name of revision, if given.
	DatasetName *string `json:"dataset_name"`

	// ID of revision, if name is given.
	DatasetId *string `json:"dataset_id"`

	// Branch of revision.
	Branch *string `json:"branch"`

	// Dashboard URL for the revision.
	DashboardURL *string `json:"dashboard_url"`

	// Number of computers for the revision.
	NumComputers int `json:"num_computers"`
	// contains filtered or unexported fields
}

func (*DatasetRevision) DownloadData 

func (d *DatasetRevision) DownloadData(ctx context.Context, directory string) error

DownloadData downloads output files pertaining to the revision to given path. Datasets are stored in Chalk as sharded Parquet files. With this method, you can download those raw files into a directory for processing with other tools.

func (*DatasetRevision) DownloadUris added in v1.2.71 

func (d *DatasetRevision) DownloadUris(ctx context.Context) ([]string, error)

DownloadUris retrieves the download URIs for the dataset revision. This method returns a list of signed URLs that can be used to download the Parquet files containing the dataset data.

Example: 

urls, err := datasetRevision.DownloadUris(context.Background())
if err != nil {
	return err
}

for _, url := range urls {
	fmt.Println(url)
}

type DatasetSampleFilter 

type DatasetSampleFilter struct {
	LowerBound *time.Time `json:"lower_bound"`
	UpperBound *time.Time `json:"upper_bound"`
	MaxSamples *int       `json:"max_samples"`
}

type ErrorCode 

type ErrorCode struct {
	Value string
}

ErrorCode indicates the type of error occurred

func (*ErrorCode) UnmarshalJSON 

func (e *ErrorCode) UnmarshalJSON(data []byte) error

type ErrorCodeCategory 

type ErrorCodeCategory struct {
	Value string
}

func (*ErrorCodeCategory) UnmarshalJSON 

func (c *ErrorCodeCategory) UnmarshalJSON(data []byte) error

type Feature 

type Feature struct {
	Fqn string
}

func UnwrapFeature 

func UnwrapFeature(t any) (result *Feature, returnErr error)

type FeatureMeta added in v1.2.0 

type FeatureMeta struct {
	ResolverFqn string
	SourceType  string
	SourceId    string
}

type FeatureOutput added in v1.2.0 

type FeatureOutput struct {
	Fqn   string
	Value any
	Meta  *FeatureMeta
}

type FeatureResolutionMeta 

type FeatureResolutionMeta struct {
	// The name of the resolver that computed the feature value.
	ChosenResolverFqn string `json:"chosen_resolver_fqn"`

	// Whether the feature request was satisfied by a cached value.
	CacheHit bool `json:"cache_hit"`

	// Primitive type name for the feature, e.g. `str` for `some_feature: str`.
	// Returned only if query-level 'include_meta' is True.
	PrimitiveType string `json:"primitive_type"`

	// The version that was selected for this feature. Defaults to `default_version`, if query
	// does not specify a constraint. If no versioning information is provided on the feature definition,
	// the default version is `1`.
	Version int `json:"version"`
}

type FeatureResult 

type FeatureResult struct {
	// The name of the feature requested, e.g. 'user.identity.has_voip_phone'.
	Field string

	// The value of the requested feature.
	// If an error was encountered in resolving this feature,
	// this field will be empty.
	Value any

	// The primary key of the resolved feature.
	Pkey any

	// The time at which this feature was computed.
	// This value could be significantly in the past if you're using caching.
	Timestamp *time.Time

	// Detailed information about how this feature was computed.
	Meta *FeatureResolutionMeta

	// The error encountered in resolving this feature.
	// If no error occurred, this field is empty.
	Error *ServerError
}

type FeatureTable added in v1.2.4 

type FeatureTable struct {
	ArrowTable arrow.Table
	// contains filtered or unexported fields
}

func MakeFeatureTable added in v1.2.4 

func MakeFeatureTable(featureToValues map[any]any, options ...MakeFeatureTableOptions) (*FeatureTable, error)

MakeFeatureTable creates an Arrow table from a map of feature to values. A feature can be either a string or a codegen'd feature reference. The values should be a slice of the appropriate type for the feature.

func (*FeatureTable) Release added in v1.2.4 

func (f *FeatureTable) Release()

func (*FeatureTable) ToBytes added in v1.2.4 

func (f *FeatureTable) ToBytes() ([]byte, error)

type FloatValue added in v0.20.2 

type FloatValue float64

func (FloatValue) ToProto added in v0.20.2 

func (v FloatValue) ToProto() (*structpb.Value, error)

type Fqn added in v0.3.6 

type Fqn = string

type GRPCClient added in v0.16.14 

type GRPCClient interface {
	// OnlineQueryBulk computes features values using online resolvers,
	// and has the ability to query multiple primary keys at once.
	//
	// The Chalk CLI can codegen structs for all available features with
	// the [chalk codegen] command.
	//
	//	Example usages:
	//
	//      // Single-namespace online query
	//  	var users []User
	//  	res, err := chalk.OnlineQueryBulk(
	//  		context.Background(),
	//  		chalk.OnlineQueryParams{}.
	//  			WithInput(Features.User.Id, []string{"u273489056"}).
	//  			WithInput(Features.User.Transactions, [][]Transaction{
	//  				{
	//  					{Id: utils.ToPtr("txn8f76"), Amount: utils.ToPtr(13.23)},
	//  					{Id: utils.ToPtr("txn546d"), Amount: utils.ToPtr(48.95)},
	//  				},
	//  			}).
	//  			WithOutputs(Features.User.Id, Features.User.WeightedScore),
	//  	)
	//  	if err != nil {
	//  		return errors.Wrap(err, "querying weighted score")
	//  	}
	//  	if err = res.UnmarshalInto(&users); err != nil {
	//  		return errors.Wrap(err, "unmarshalling into users")
	//  	}
	//  	fmt.Println("user %s has weighted score %v", users[0].Id, users[0].WeightedScore)
	//
	//
	//  	// Multi-namespace online query
	//  	type underwriting struct {
	//  		User
	//  		Loan
	//  	}
	//
	//  	res, err := chalk.OnlineQueryBulk(
	//  		context.Background(),
	//  		chalk.OnlineQueryParams{}.
	//  			WithInput(Features.User.Id, []string{"u273489056"}).
	//  			WithInput(Features.Loan.Id, []string{"l273489056"}).
	//  			WithOutputs(
	//  				Features.User.Id,
	//  				Features.User.WeightedScore,
	//  				Features.Loan.Id,
	//  				Features.Loan.ApprovalStatus,
	//  			),
	//  	)
	//  	if err != nil {
	//  		return errors.Wrap(err, "querying weighted score and loan approval status")
	//  	}
	//
	//  	var root []underwriting
	//  	if err = res.UnmarshalInto(&root); err != nil {
	//  		return errors.Wrap(err, "unmarshalling into underwriting")
	//  	}
	//  	fmt.Println("user %s has weighted score %v", root[0].User.Id, root[0].User.WeightedScore)
	//  	fmt.Println("loan %s has approval status %v", root[0].Loan.Id, root[0].Loan.ApprovalStatus)
	//
	// [chalk codegen]: https://docs.chalk.ai/cli#codegen
	// [query basics]: https://docs.chalk.ai/docs/query-basics
	OnlineQueryBulk(ctx context.Context, params OnlineQueryParamsComplete) (*GRPCOnlineQueryBulkResult, error)
	GetOnlineQueryBulkRequest(ctx context.Context, params OnlineQueryParamsComplete) (*connect.Request[commonv1.OnlineQueryBulkRequest], error)
	GetQueryEndpoint() string

	// UpdateAggregates synchronously persists feature values that back windowed aggregations,
	// while updating the corresponding aggregate values themselves.
	// The `Inputs` parameter should be a map of features to values. The features should either
	// be a string or codegen-ed feature reference, and the values a slice of the appropriate type.
	// All slices should be the same length.
	//
	// The update is successful if the response contains no errors.
	//
	// Example:
	//
	// 		res, err := client.UpdateAggregates(
	//			context.Background(),
	// 			UpdateAggregatesParams{
	// 				Inputs: map[any]any{
	// 					Features.Txns.Id: []string{5555-5555", "4444-4444"},
	// 				    "txns.merchant_id": []string{"amezon", "pacman studios"},
	//					"txns.amount": []float64{126.58, 100.03},
	// 				},
	// 			}
	// 		)
	//      if err != nil {
	//          return errors.Wrap(err, "updating aggregates for merchant")
	//      }
	//
	// [chalk codegen]: https://docs.chalk.ai/cli#codegen
	UpdateAggregates(ctx context.Context, params UpdateAggregatesParams) (*GRPCUpdateAggregatesResult, error)

	GetAggregates(ctx context.Context, features []string) (*GRPCGetAggregatesResult, error)

	PlanAggregateBackfill(
		ctx context.Context,
		req *aggregatev1.PlanAggregateBackfillRequest,
	) (*GRPCPlanAggregateBackfillResult, error)

	// GetToken retrieves a token that can be used to authenticate requests to the Chalk API
	// along with other using the client's credentials.
	GetToken(ctx context.Context) (*TokenResult, error)

	// GetConfig retrieves the current configuration of the GRPCClient.
	// This will not necessarily be the same config as was used to create the
	// GRPCClient, as default values may have been set.
	GetConfig() *GRPCClientConfig

	GetMetadataServerInterceptor() []connect.ClientOption
}

GRPCClient is the gRPC interface for interacting with Chalk.

func NewGRPCClient added in v0.16.14 

func NewGRPCClient(ctx context.Context, configs ...*GRPCClientConfig) (GRPCClient, error)

NewGRPCClient creates a GRPCClient with authentication settings configured. These settings can be overriden by passing in a GRPCClientConfig object. Otherwise, for each configuration variable, NewGRPCClient uses its corresponding environment variable if it exists. The environment variables that NewGRPCClient looks for are: 

CHALK_ACTIVE_ENVIRONMENT
CHALK_API_SERVER
CHALK_CLIENT_ID
CHALK_CLIENT_SECRET

For each config variable, if it is still not found, NewGRPCClient will look for a `~/.chalk.yml` file, which is updated when you run chalk login. If a configuration for the specific project directory if found, that configuration will be used. Otherwise, the configuration under the key `default` will be used.

Example: 

	     chalkClient, err := chalk.NewGRPCClient(
             context.Background(),
	         &chalk.GRPCClientConfig{
		         ClientId:      "id-89140a6614886982a6782106759e30",
		         ClientSecret:  "sec-b1ba98e658d7ada4ff4c7464fb0fcee65fe2cbd86b3dd34141e16f6314267b7b",
		         ApiServer:     "https://api.chalk.ai",
		         EnvironmentId: "qa",
		         Branch:        "jorges-december",
	         },
	     )

type GRPCClientConfig added in v0.16.14 

type GRPCClientConfig struct {
	ClientId      string
	ClientSecret  string
	ApiServer     string
	EnvironmentId string

	// If specified, Chalk will route all requests from this client
	// instance to the relevant branch.
	Branch string

	// Chalk routes performance sensitive requests like online query
	// directly to the query server that runs the engine. Populate
	// this field if you would like to route these requests to a
	// different query server than the one automatically resolved
	// by Chalk.
	QueryServer string

	// Logger is the logger that the backend will use to log errors,
	// warnings, and informational messages.
	//
	// LeveledLogger is implemented by StdOutLeveledLogger, and one can be
	// initialized at the desired level of logging.  LeveledLogger
	// also provides out-of-the-box compatibility with a Logrus Logger, but may
	// require a thin shim for use with other logging libraries that use less
	// standard conventions like Zap.
	//
	// Defaults to DefaultLeveledLogger.
	//
	// To set a logger that logs nothing, set this to a chalk.LeveledLogger
	// with a Level of LevelNull (simply setting this field to nil will not
	// work).
	Logger LeveledLogger

	// HTTPClient is an HTTP client instance to use when instantiating a
	// Connect gRPC-compatible client.
	//
	// If left unset, it'll be set to a default HTTP client for the package.
	HTTPClient HTTPClient

	// Chalk can route queries to specific deployments using deployment
	// tags.
	DeploymentTag string

	// ResourceGroup specifies the resource group to route all requests to. If set
	// on the request or query level, this will be overridden.
	ResourceGroup string

	// Timeout specifies the timeout for all requests. Defaults to no timeout.
	// Timeout of 0 means no timeout. Deadline or timeout set on the request
	// context will override this timeout.
	Timeout time.Duration

	// Allocator specifies the allocator to use for creating Arrow objects.
	// Defaults to `memory.DefaultAllocator`.
	Allocator memory.Allocator

	// Interceptors are middleware functions that can intercept and modify
	// gRPC requests and responses for logging, auth, metrics, etc.
	Interceptors []connect.Interceptor
}

type GRPCGetAggregatesResult added in v1.2.0 

type GRPCGetAggregatesResult struct {
	RawResponse *aggregatev1.GetAggregatesResponse
}

type GRPCOnlineQueryBulkResult added in v1.2.0 

type GRPCOnlineQueryBulkResult struct {
	RawResponse *commonv1.OnlineQueryBulkResponse
	// contains filtered or unexported fields
}

func NewGRPCOnlineQueryBulkResult added in v1.2.31 

func NewGRPCOnlineQueryBulkResult(
	response *commonv1.OnlineQueryBulkResponse,
	options ...NewGRPCOnlineQueryBulkResultOptions,
) (*GRPCOnlineQueryBulkResult, error)

NewGRPCOnlineQueryBulkResult creates a GRPCOnlineQueryBulkResult for testing. This function sets up a result object with Arrow artifacts such as a `memory.Allocator` which is required during unmarshalling operations.

func (*GRPCOnlineQueryBulkResult) GetErrors added in v1.2.0 

func (r *GRPCOnlineQueryBulkResult) GetErrors() ([]ServerError, error)

func (*GRPCOnlineQueryBulkResult) GetQueryMeta added in v1.2.0 

func (r *GRPCOnlineQueryBulkResult) GetQueryMeta() *QueryMeta

func (*GRPCOnlineQueryBulkResult) GetRow added in v1.2.0 

func (r *GRPCOnlineQueryBulkResult) GetRow(rowIndex int) (*RowResult, error)

func (*GRPCOnlineQueryBulkResult) GetTable added in v1.2.1 

func (r *GRPCOnlineQueryBulkResult) GetTable() (arrow.Table, error)

func (*GRPCOnlineQueryBulkResult) UnmarshalInto added in v1.2.0 

func (r *GRPCOnlineQueryBulkResult) UnmarshalInto(resultHolders any) error

type GRPCPlanAggregateBackfillResult added in v1.2.0 

type GRPCPlanAggregateBackfillResult struct {
	RawResponse *aggregatev1.PlanAggregateBackfillResponse
}

type GRPCUpdateAggregatesResult added in v1.2.0 

type GRPCUpdateAggregatesResult struct {
	RawResponse *commonv1.UploadFeaturesBulkResponse
}

func (*GRPCUpdateAggregatesResult) GetErrors added in v1.2.0 

func (r *GRPCUpdateAggregatesResult) GetErrors() ([]ServerError, error)

type GetOfflineQueryJobResponse 

type GetOfflineQueryJobResponse struct {
	IsFinished bool             `json:"is_finished"`
	Version    int              `json:"version"`
	Urls       []string         `json:"urls"`
	Errors     []ServerError    `json:"errors"`
	Columns    []ColumnMetadata `json:"columns"`
}

type GetOfflineQueryStatusParams added in v1.2.70 

type GetOfflineQueryStatusParams struct {
	// JobId is the ID of the offline query job to check.
	JobId string `json:"job_id"`

	// PreviewDeploymentId, if specified, will be used by Chalk to route
	// your request to the relevant preview deployment.
	PreviewDeploymentId string `json:"preview_deployment_id"`
}

GetOfflineQueryStatusParams defines the parameters that help you execute a get offline query status request.

type GetOfflineQueryStatusResult added in v1.2.70 

type GetOfflineQueryStatusResult struct {
	Report BatchReport `json:"report"`
}

GetOfflineQueryStatusResult holds the result of a get offline query status request.

type GetRunStatusParams 

type GetRunStatusParams struct {
	// RunId is the ID of the resolver run to check.
	RunId string `json:"resolver_fqn"`

	// PreviewDeploymentId, if specified, will be used by Chalk to route
	// your request to the relevant preview deployment.
	PreviewDeploymentId string `json:"preview_deployment_id"`
}

type GetRunStatusResult 

type GetRunStatusResult struct {
	// Id is the ID of the resolver run.
	Id string `json:"id"`

	// Status is the current status of the resolver run.
	Status string `json:"status"`
}

type HTTPClient added in v0.3.8 

type HTTPClient interface {
	Do(req *http.Request) (*http.Response, error)
	Get(url string) (resp *http.Response, err error)
}

type HTTPError 

type HTTPError struct {
	// The URL of the HTTP request made.
	Path string

	// The message describing the error.
	Message string

	// HTTP status code of the error.
	StatusCode int

	// The size of the message body, in bytes.
	ContentLength int64

	// A Chalk Trace ID, useful for when contacting Chalk Support.
	Trace *string
}

HTTPError is a wrapper around a standard HTTP error such as missing authorization.

func (*HTTPError) Error 

func (e *HTTPError) Error() string

type Level 

type Level uint32

Level represents a logging level. 

const (
	// LevelNull sets a logger to show no messages at all.
	LevelNull Level = 0

	// LevelError sets a logger to show error messages only.
	LevelError Level = 1

	// LevelWarn sets a logger to show warning messages or anything more
	// severe.
	LevelWarn Level = 2

	// LevelInfo sets a logger to show informational messages or anything more
	// severe.
	LevelInfo Level = 3

	// LevelDebug sets a logger to show informational messages or anything more
	// severe.
	LevelDebug Level = 4
)

type LeveledLogger 

type LeveledLogger interface {
	// Debugf logs a debug message using Printf conventions.
	Debugf(format string, v ...interface{})

	// Errorf logs a warning message using Printf conventions.
	Errorf(format string, v ...interface{})

	// Infof logs an informational message using Printf conventions.
	Infof(format string, v ...interface{})

	// Warnf logs a warning message using Printf conventions.
	Warnf(format string, v ...interface{})
}

LeveledLogger provides a basic leveled logging interface for printing debug, informational, warning, and error messages.

It's implemented by StdOutLeveledLogger and also provides out-of-the-box compatibility with a Logrus Logger, but may require a thin shim for use with other logging libraries that you use less standard conventions like Zap. 

var DefaultLeveledLogger LeveledLogger = &StdOutLeveledLogger{
	Level: LevelError,
}

DefaultLeveledLogger is the default logger that the library will use to log errors, warnings, and informational messages.

LeveledLogger is implemented by StdOutLeveledLogger, and one can be initialized at the desired level of logging. LeveledLogger also provides out-of-the-box compatibility with a Logrus Logger, but may require a thin shim for use with other logging libraries that use less standard conventions like Zap.

This Logger will be inherited by any backends created by default, but will be overridden if a backend is created with GetBackendWithConfig with a custom StdOutLeveledLogger set.

type MakeFeatureTableOptions added in v1.2.4 

type MakeFeatureTableOptions struct {
	// Defaults to memory.DefaultAllocator
	Allocator memory.Allocator
}

type NewGRPCOnlineQueryBulkResultOptions added in v1.2.31 

type NewGRPCOnlineQueryBulkResultOptions struct {
	Allocator memory.Allocator
}

type OfflineQueryParams 

type OfflineQueryParams struct {

	// The environment under which to run the resolvers.
	// API tokens can be scoped to an environment.
	// If no environment is specified in the query,
	// but the token supports only a single environment,
	// then that environment will be taken as the scope
	// for executing the request.
	EnvironmentId string

	// A unique name that if provided will be used to generate and
	// save a Dataset constructed from the list of features computed
	// from the inputs.
	DatasetName string

	// The branch under which to run the resolvers.
	Branch string

	// The maximum number of samples to include in the `DataFrame`.
	MaxSamples *int

	// DefaultTime indicates the default time at which you would like to observe the features.
	// If not specified, the current time will be used as the default observation time.
	// The default observation time will be used when:
	// 1. A feature value is passed into [OfflineQueryParams.WithInput] as a [TsFeatureValue] with a nil time.
	// 2. A feature value is passed into [OfflineQueryParams.WithInput] as a raw value (not a [TsFeatureValue]).
	// For more information about observation time, see https://docs.chalk.ai/docs/temporal-consistency
	DefaultTime *time.Time

	// The tags used to scope the resolvers.
	Tags []string

	QueryContext *QueryContext

	// A globally unique ID for the query, used alongside logs and available in web
	// interfaces. If empty, a correlation ID will be generated for you and returned on
	// the response.
	CorrelationId string

	// RequiredResolverTags are all the [tags] that must be present on a resolver for
	// it to be considered eligible to execute.
	// [tags]: https://docs.chalk.ai/docs/resolver-tags
	RequiredResolverTags []string

	// Map of additional options to pass to the Chalk query engine. Values may be provided
	// as part of conversations with Chalk Support to enable or disable specific
	// functionality.
	PlannerOptions map[string]any

	// RunAsynchronously boots a kubernetes job to run the queries in their own pods,
	// separate from the engine and branch servers. This is useful for large datasets
	// and jobs that require a long time to run.
	RunAsynchronously bool

	// NumShards specifies the number of shards to split the input across.
	// If specified, the query will be run asynchronously.
	NumShards *int

	// NumWorkers specifies the maximum number of pod workers to run at any time.
	// This parameter is useful if you have a large number of shards and would like
	// to limit the number of pods running at once.
	NumWorkers *int

	// Resources override resource requests for processes with isolated resources,
	// e.g., offline queries and cron jobs.
	Resources *ResourceRequests

	// CompletionDeadline specifies the duration shards must complete within,
	// or they will be terminated. Terminated shards can be retried.
	CompletionDeadline *time.Duration

	// MaxRetries specifies the number of times failed offline query shards will be retried.
	// The retry budget is shared across all shards. By default, max_retries=num_shards.
	MaxRetries *int

	// StoreOnline specifies whether the output of the query will be stored in the online store.
	StoreOnline bool

	// StoreOffline specifies whether the output of the query will be stored in the offline store.
	StoreOffline bool

	// UseMultipleComputers specifies whether to use multiple computers for the query.
	UseMultipleComputers bool

	// UploadInputAsTable specifies whether to upload the input as a table.
	UploadInputAsTable bool

	// EnvOverrides specifies environment variable overrides for the query execution.
	EnvOverrides map[string]string

	// EnableProfiling enables profiling for the query execution.
	EnableProfiling bool

	// StorePlanStages triggers storing the output of each of the query plan stages in
	// S3/GCS. This will dramatically impact the performance of the query, so it should
	// only be used for debugging. These files will be visible in the web dashboard's
	// query detail view, and can be downloaded in full by clicking on a plan node in
	// the query plan visualizer.
	StorePlanStages bool

	// Explain will log the query execution plan. Requests using `explain=True` will be
	// slower than requests using `explain=False`.
	Explain bool

	// RecomputeFeatures forces recomputation of features instead of using cached values.
	RecomputeFeatures bool

	// ObservedAtLowerBound specifies the lower bound for the observation time.
	// Features will be queried as of this time or later.
	ObservedAtLowerBound *time.Time

	// ObservedAtUpperBound specifies the upper bound for the observation time.
	// Features will be queried as of this time or earlier.
	ObservedAtUpperBound *time.Time

	// SampleFeatures is a list of features to sample.
	SampleFeatures []string

	// SpineSqlQuery is an alternative way to specify inputs - a SQL query that retrieves outputs.
	SpineSqlQuery string

	// RecomputeRequestRevisionId is the revision ID for recompute requests.
	RecomputeRequestRevisionId string

	// OverrideTargetImageTag specifies the image tag to use for the query execution.
	OverrideTargetImageTag string

	// FeatureForLowerUpperBound specifies the feature to use for lower/upper bound calculations.
	FeatureForLowerUpperBound string

	// UseJobQueue specifies whether to use the job queue for processing.
	UseJobQueue bool

	// OverlayGraph specifies additional features and resolvers to be used to plan this specific query.
	OverlayGraph string
	// contains filtered or unexported fields
}

OfflineQueryParams defines the parameters that help you execute an online query. OfflineQueryParams is the starting point of the method chain that can help you obtain an object of type OfflineQueryParamsComplete that you can pass into Client.OfflineQuery.

func (OfflineQueryParams) WithInput 

func (p OfflineQueryParams) WithInput(feature any, values []any) offlineQueryParamsWithInputs

WithInput returns a copy of Offline Query parameters with the specified inputs added. For use via method chaining. See OfflineQueryParamsComplete for usage examples. The "values" argument can contain a raw value (int or string), or it can also contain a TsFeatureValue if you want to query with a specific observation time. The observation time for raw values will be the default observation time specified as [OfflineQueryParams.DefaultTime]. If no default observation time is specified, the current time will be used. For more information about observation time, see Temporal Consistency.

func (OfflineQueryParams) WithInputs added in v0.17.1 

func (p OfflineQueryParams) WithInputs(inputs map[any][]any) offlineQueryParamsWithInputs

WithInputs returns a copy of Offline Query parameters with the specified inputs added. For use via method chaining. See OfflineQueryParamsComplete for usage examples. The value of the inputs map can contain a raw value (int or string), or it can also contain a TsFeatureValue if you want to query with a specific observation time. The observation time for raw values will be the default observation time specified as [OfflineQueryParams.DefaultTime]. If no default observation time is specified, the current time will be used. For more information about observation time, see Temporal Consistency.

func (OfflineQueryParams) WithOutputs 

func (p OfflineQueryParams) WithOutputs(features ...any) OfflineQueryParamsComplete

WithOutputs returns a copy of Offline Query parameters with the specified outputs added. For use via method chaining. See OfflineQueryParamsComplete for usage examples.

func (OfflineQueryParams) WithRequiredOutputs 

func (p OfflineQueryParams) WithRequiredOutputs(features ...any) OfflineQueryParamsComplete

WithRequiredOutputs returns a copy of Offline Query parameters with the specified outputs added. For use via method chaining. See OfflineQueryParamsComplete for usage examples.

type OfflineQueryParamsComplete 

type OfflineQueryParamsComplete struct {
	// contains filtered or unexported fields
}

OfflineQueryParamsComplete is the only type of object accepted as an argument to Client.OfflineQuery. OfflineQueryParamsComplete is obtained by calling a chain of methods starting with any method of OfflineQueryParams.

Example: 

     defaultObservedAt := time.Now().Add(-time.Hour)
		observedAt, _ := time.Parse(time.RFC822, "02 Jan 22 15:04 PST")
		client.OfflineQuery(
			context.Background(),
			OfflineQueryParams{
				EnvironmentId: "pipkjlfc3gtmn",
			}.
	 		WithInput(Features.User.Id, []any{1, chalk.TsFeatureValue{Value: 2, ObservationTime: &observedAt}}).
	 		WithRequiredOutputs(Features.User.Email, Features.User.Card.Id),
		)

It is mandatory to call [OfflineQueryParams.WithOutput] or OfflineQueryParams.WithRequiredOutputs at least once for OfflineQueryParamsComplete to be returned. Otherwise, an incomplete type will be returned, and it cannot be passed into Client.OfflineQuery.

func (OfflineQueryParamsComplete) WithCompletionDeadline added in v1.2.69 

func (p OfflineQueryParamsComplete) WithCompletionDeadline(deadline time.Duration) OfflineQueryParamsComplete

WithCompletionDeadline returns a copy of Offline Query parameters with CompletionDeadline set. For use via method chaining. See OfflineQueryParamsComplete for usage examples.

func (OfflineQueryParamsComplete) WithCorrelationId added in v1.2.71 

func (p OfflineQueryParamsComplete) WithCorrelationId(correlationId string) OfflineQueryParamsComplete

WithCorrelationId returns a copy of Offline Query parameters with the specified correlation ID set.

func (OfflineQueryParamsComplete) WithEnableProfiling added in v1.2.69 

func (p OfflineQueryParamsComplete) WithEnableProfiling(enableProfiling bool) OfflineQueryParamsComplete

WithEnableProfiling returns a copy of Offline Query parameters with EnableProfiling set. For use via method chaining. See OfflineQueryParamsComplete for usage examples.

func (OfflineQueryParamsComplete) WithEnvOverrides added in v1.2.69 

func (p OfflineQueryParamsComplete) WithEnvOverrides(envOverrides map[string]string) OfflineQueryParamsComplete

WithEnvOverrides returns a copy of Offline Query parameters with EnvOverrides set. For use via method chaining. See OfflineQueryParamsComplete for usage examples.

func (OfflineQueryParamsComplete) WithExplain added in v1.2.71 

func (p OfflineQueryParamsComplete) WithExplain(explain bool) OfflineQueryParamsComplete

WithExplain returns a copy of Offline Query parameters with the specified explain setting.

func (OfflineQueryParamsComplete) WithFeatureForLowerUpperBound added in v1.2.71 

func (p OfflineQueryParamsComplete) WithFeatureForLowerUpperBound(feature string) OfflineQueryParamsComplete

WithFeatureForLowerUpperBound returns a copy of Offline Query parameters with the specified feature for lower/upper bound set.

func (OfflineQueryParamsComplete) WithInput 

func (p OfflineQueryParamsComplete) WithInput(feature any, values []any) OfflineQueryParamsComplete

WithInput returns a copy of Offline Query parameters with the specified input added. For use via method chaining. See OfflineQueryParamsComplete for usage examples.

func (OfflineQueryParamsComplete) WithMaxRetries added in v1.2.69 

func (p OfflineQueryParamsComplete) WithMaxRetries(maxRetries int) OfflineQueryParamsComplete

WithMaxRetries returns a copy of Offline Query parameters with MaxRetries set. For use via method chaining. See OfflineQueryParamsComplete for usage examples.

func (OfflineQueryParamsComplete) WithNumShards added in v1.2.69 

func (p OfflineQueryParamsComplete) WithNumShards(numShards int) OfflineQueryParamsComplete

WithNumShards returns a copy of Offline Query parameters with NumShards set. For use via method chaining. See OfflineQueryParamsComplete for usage examples.

func (OfflineQueryParamsComplete) WithNumWorkers added in v1.2.69 

func (p OfflineQueryParamsComplete) WithNumWorkers(numWorkers int) OfflineQueryParamsComplete

WithNumWorkers returns a copy of Offline Query parameters with NumWorkers set. For use via method chaining. See OfflineQueryParamsComplete for usage examples.

func (OfflineQueryParamsComplete) WithObservedAtLowerBound added in v1.2.71 

func (p OfflineQueryParamsComplete) WithObservedAtLowerBound(lowerBound time.Time) OfflineQueryParamsComplete

WithObservedAtLowerBound returns a copy of Offline Query parameters with the specified observed at lower bound set.

func (OfflineQueryParamsComplete) WithObservedAtUpperBound added in v1.2.71 

func (p OfflineQueryParamsComplete) WithObservedAtUpperBound(upperBound time.Time) OfflineQueryParamsComplete

WithObservedAtUpperBound returns a copy of Offline Query parameters with the specified observed at upper bound set.

func (OfflineQueryParamsComplete) WithOutputs 

func (p OfflineQueryParamsComplete) WithOutputs(features ...any) OfflineQueryParamsComplete

WithOutputs returns a copy of Offline Query parameters with the specified outputs added. For use via method chaining. See OfflineQueryParamsComplete for usage examples.

func (OfflineQueryParamsComplete) WithOverlayGraph added in v1.2.71 

func (p OfflineQueryParamsComplete) WithOverlayGraph(overlayGraph string) OfflineQueryParamsComplete

WithOverlayGraph returns a copy of Offline Query parameters with the specified overlay graph set.

func (OfflineQueryParamsComplete) WithOverrideTargetImageTag added in v1.2.71 

func (p OfflineQueryParamsComplete) WithOverrideTargetImageTag(imageTag string) OfflineQueryParamsComplete

WithOverrideTargetImageTag returns a copy of Offline Query parameters with the specified override target image tag set.

func (OfflineQueryParamsComplete) WithPlannerOptions added in v1.2.71 

func (p OfflineQueryParamsComplete) WithPlannerOptions(options map[string]any) OfflineQueryParamsComplete

WithPlannerOptions returns a copy of Offline Query parameters with the specified planner options set.

func (OfflineQueryParamsComplete) WithRecomputeFeatures added in v1.2.71 

func (p OfflineQueryParamsComplete) WithRecomputeFeatures(recomputeFeatures bool) OfflineQueryParamsComplete

WithRecomputeFeatures returns a copy of Offline Query parameters with the specified recompute features setting.

func (OfflineQueryParamsComplete) WithRecomputeRequestRevisionId added in v1.2.71 

func (p OfflineQueryParamsComplete) WithRecomputeRequestRevisionId(revisionId string) OfflineQueryParamsComplete

WithRecomputeRequestRevisionId returns a copy of Offline Query parameters with the specified recompute request revision ID set.

func (OfflineQueryParamsComplete) WithRequiredOutputs 

func (p OfflineQueryParamsComplete) WithRequiredOutputs(features ...any) OfflineQueryParamsComplete

WithRequiredOutputs returns a copy of Offline Query parameters with the specified outputs added. For use via method chaining. See OfflineQueryParamsComplete for usage examples.

func (OfflineQueryParamsComplete) WithRequiredResolverTags added in v1.2.71 

func (p OfflineQueryParamsComplete) WithRequiredResolverTags(tags []string) OfflineQueryParamsComplete

WithRequiredResolverTags returns a copy of Offline Query parameters with the specified required resolver tags set.

func (OfflineQueryParamsComplete) WithResources added in v1.2.69 

func (p OfflineQueryParamsComplete) WithResources(resources *ResourceRequests) OfflineQueryParamsComplete

WithResources returns a copy of Offline Query parameters with Resources set. For use via method chaining. See OfflineQueryParamsComplete for usage examples.

func (OfflineQueryParamsComplete) WithRunAsynchronously added in v1.2.69 

func (p OfflineQueryParamsComplete) WithRunAsynchronously(runAsynchronously bool) OfflineQueryParamsComplete

WithRunAsynchronously returns a copy of Offline Query parameters with RunAsynchronously set. For use via method chaining. See OfflineQueryParamsComplete for usage examples.

func (OfflineQueryParamsComplete) WithSampleFeatures added in v1.2.71 

func (p OfflineQueryParamsComplete) WithSampleFeatures(sampleFeatures []string) OfflineQueryParamsComplete

WithSampleFeatures returns a copy of Offline Query parameters with the specified sample features set.

func (OfflineQueryParamsComplete) WithSpineSqlQuery added in v1.2.71 

func (p OfflineQueryParamsComplete) WithSpineSqlQuery(spineSqlQuery string) OfflineQueryParamsComplete

WithSpineSqlQuery returns a copy of Offline Query parameters with the specified spine SQL query set.

func (OfflineQueryParamsComplete) WithStoreOffline added in v1.2.69 

func (p OfflineQueryParamsComplete) WithStoreOffline(storeOffline bool) OfflineQueryParamsComplete

WithStoreOffline returns a copy of Offline Query parameters with StoreOffline set. For use via method chaining. See OfflineQueryParamsComplete for usage examples.

func (OfflineQueryParamsComplete) WithStoreOnline added in v1.2.69 

func (p OfflineQueryParamsComplete) WithStoreOnline(storeOnline bool) OfflineQueryParamsComplete

WithStoreOnline returns a copy of Offline Query parameters with StoreOnline set. For use via method chaining. See OfflineQueryParamsComplete for usage examples.

func (OfflineQueryParamsComplete) WithStorePlanStages added in v1.2.71 

func (p OfflineQueryParamsComplete) WithStorePlanStages(storePlanStages bool) OfflineQueryParamsComplete

WithStorePlanStages returns a copy of Offline Query parameters with the specified store plan stages setting.

func (OfflineQueryParamsComplete) WithUploadInputAsTable added in v1.2.69 

func (p OfflineQueryParamsComplete) WithUploadInputAsTable(uploadInputAsTable bool) OfflineQueryParamsComplete

WithUploadInputAsTable returns a copy of Offline Query parameters with UploadInputAsTable set. For use via method chaining. See OfflineQueryParamsComplete for usage examples.

func (OfflineQueryParamsComplete) WithUseJobQueue added in v1.2.71 

func (p OfflineQueryParamsComplete) WithUseJobQueue(useJobQueue bool) OfflineQueryParamsComplete

WithUseJobQueue returns a copy of Offline Query parameters with the specified use job queue setting.

func (OfflineQueryParamsComplete) WithUseMultipleComputers added in v1.2.69 

func (p OfflineQueryParamsComplete) WithUseMultipleComputers(useMultipleComputers bool) OfflineQueryParamsComplete

WithUseMultipleComputers returns a copy of Offline Query parameters with UseMultipleComputers set. For use via method chaining. See OfflineQueryParamsComplete for usage examples.

type OnlineQueryBulkResponse added in v0.3.6 

type OnlineQueryBulkResponse struct {
	QueryResults map[QueryName]onlineQueryResultFeather
	// contains filtered or unexported fields
}

func (*OnlineQueryBulkResponse) Unmarshal added in v0.3.6 

func (r *OnlineQueryBulkResponse) Unmarshal(body []byte) error

type OnlineQueryBulkResult added in v0.3.6 

type OnlineQueryBulkResult struct {
	// ScalarsTable is an Arrow Table containing
	// scalar features of the target feature class.
	ScalarsTable arrow.Table

	// GroupsTables is a map from a has-many feature to its
	// corresponding Arrow Table.
	GroupsTables map[string]arrow.Table

	// Execution metadata for the query. See QueryMeta for details.
	Meta *QueryMeta
	// contains filtered or unexported fields
}

OnlineQueryBulkResult holds the result of a bulk online query.

func (OnlineQueryBulkResult) Release added in v0.3.7 

func (r OnlineQueryBulkResult) Release()

func (*OnlineQueryBulkResult) UnmarshalInto added in v0.7.0 

func (r *OnlineQueryBulkResult) UnmarshalInto(resultHolders any) error

UnmarshalInto unmarshals Arrow tables in OnlineQueryBulkResult into the specified slice of structs (passed by pointer). The input argument should be a pointer to the empty slice of structs that represents the output namespace.

  1. UnmarshalInto populates fields corresponding to outputs specified in OnlineQueryParams, while leaving all other fields as nil. If the struct has fields that point to other structs (has-one relations), those nested structs will also be populated with their respective feature values.

  2. UnmarshalInto also returns an error if its argument is not a pointer to a list of structs.

  3. UnmarshalInto does not currently handle unmarshalling: a. has-many features In the meantime, you can manually unmarshal a has-many feature across all root structs by using the UnmarshalTableInto function.

Usage example: 

func printUserDetails(chalkClient chalk.Client) {
	result, _ := chalkClient.OnlineQueryBulk(
  	    context.Background(),
  	    chalk.OnlineQueryParams{}.WithOutputs(
		    Features.User.Family.Size,
		    Features.User.SocureScore
	    ).WithInput(Features.User.Id, []int{1, 2}),
	    nil,
	)

	var users []User
	result.UnmarshalInto(&users)

	fmt.Println("User 1 family size: ", *user[0].Family.Size)
	fmt.Println("User 2 Socure score: ", *user[1].SocureScore)
}

To ensure fast unmarshals, see `WarmUpUnmarshaller`.

type OnlineQueryParams 

type OnlineQueryParams struct {

	// If true, returns metadata about the query execution in the response.
	IncludeMeta bool

	// The environment under which to run the resolvers. API tokens can be scoped to an
	// environment. If no environment is specified in the query, but the token supports
	// only a single environment, then that environment will be taken as the scope for
	// executing the request.
	EnvironmentId string

	// The tags used to scope the resolvers.
	Tags []string

	// If specified, Chalk will route your request to the relevant preview deployment.
	PreviewDeploymentId string

	// The name for class of query you're making, for example, "loan_application_model".
	QueryName string

	// The version of the query you're making, for example, "v1".
	QueryNameVersion string

	// A globally unique ID for the query, used alongside logs and available in web
	// interfaces. If None, a correlation ID will be generated for you and returned on
	// the response.
	CorrelationId string

	// Arbitrary key:value pairs to associate with a query.
	Meta map[string]string

	QueryContext *QueryContext

	// The branch id
	BranchId *string

	// RequiredResolverTags are all the [tags] that must be present on a resolver for
	// it to be considered eligible to execute.
	// [tags]: https://docs.chalk.ai/docs/resolver-tags
	RequiredResolverTags []string

	// Now is the time value that will be passed into [Now] dependent resolvers.
	// [Now]: https://docs.chalk.ai/docs/time#now-explicitly-time-dependent-resolvers
	Now []time.Time

	// StorePlanStages triggers storing the output of each of the query plan stages in
	// S3/GCS. This will dramatically impact the performance of the query, so it should
	// only be used for debugging. These files will be visible in the web dashboard's
	// query detail view, and can be downloaded in full by clicking on a plan node in
	// the query plan visualizer.
	StorePlanStages bool

	// Explain will log the query execution plan. Requests using `explain=True` will be
	// slower than requests using `explain=False`. If `true`, `IncludeMeta` will be set
	// to `true` as well.
	Explain bool

	// ResourceGroup specifies the resource group to route this query to. Takes precedence
	// over the resource group specified on the client level.
	ResourceGroup string

	// Map of additional options to pass to the Chalk query engine. Values may be provided
	// as part of conversations with Chalk Support to enable or disable specific
	// functionality.
	PlannerOptions map[string]any
	// contains filtered or unexported fields
}

OnlineQueryParams defines the parameters that help you execute an online query. OnlineQueryParams is the starting point of the method chain that can help you obtain an object of type OnlineQueryParamsComplete that you can pass into Client.OnlineQuery.

func (OnlineQueryParams) WithBranchId added in v0.4.7 

func (p OnlineQueryParams) WithBranchId(branchId string) OnlineQueryParams

WithBranchId returns a copy of Online Query parameters with the branch id added. For use via method chaining. See OnlineQueryParamsComplete for usage examples.

func (OnlineQueryParams) WithInput 

func (p OnlineQueryParams) WithInput(feature any, value any) onlineQueryParamsWithInputs

WithInput returns a copy of Online Query parameters with the specified inputs added. For use via method chaining. See OnlineQueryParamsComplete for usage examples.

func (OnlineQueryParams) WithInputs added in v0.17.1 

func (p OnlineQueryParams) WithInputs(inputs map[any]any) onlineQueryParamsWithInputs

WithInputs returns a copy of Online Query parameters with the specified inputs added. For use via method chaining. See OnlineQueryParamsComplete for usage examples.

func (OnlineQueryParams) WithOutputs 

func (p OnlineQueryParams) WithOutputs(features ...any) onlineQueryParamsWithOutputs

WithOutputs returns a copy of Online Query parameters with the specified outputs added. For use via method chaining. See OnlineQueryParamsComplete for usage examples.

func (OnlineQueryParams) WithQueryName added in v0.14.0 

func (p OnlineQueryParams) WithQueryName(name string) onlineQueryParamsWithOutputs

WithQueryName returns a copy of Online Query parameters with the specified query name set. For use via method chaining. See OnlineQueryParamsComplete for usage examples.

func (OnlineQueryParams) WithQueryNameVersion added in v0.14.0 

func (p OnlineQueryParams) WithQueryNameVersion(version string) OnlineQueryParams

WithQueryNameVersion returns a copy of Online Query parameters with the query name version added. For use via method chaining. See OnlineQueryParamsComplete for usage examples.

func (OnlineQueryParams) WithStaleness 

func (p OnlineQueryParams) WithStaleness(feature any, duration time.Duration) OnlineQueryParams

WithStaleness returns a copy of Online Query parameters with the specified staleness added. For use via method chaining. See OnlineQueryParamsComplete for usage examples. See https://docs.chalk.ai/docs/query-caching for more information on staleness.

func (OnlineQueryParams) WithTags added in v0.17.4 

func (p OnlineQueryParams) WithTags(feature ...string) OnlineQueryParams

WithTags returns a copy of Online Query parameters with the specified tags added. For use via method chaining. See OnlineQueryParamsComplete for usage examples.

type OnlineQueryParamsComplete 

type OnlineQueryParamsComplete struct {
	// contains filtered or unexported fields
}

OnlineQueryParamsComplete is the only type of object accepted as an argument to Client.OnlineQuery. OnlineQueryParamsComplete is obtained by calling a chain of methods starting with any method of OnlineQueryParams.

Example: 

	client.OnlineQuery(
		context.Background(),
		OnlineQueryParams{
			IncludeMeta: true,
			EnvironmentId: "pipkjlfc3gtmn",
		}.
 		WithInput(Features.User.Card.Id, 4).
 		WithOutputs(Features.User.Email, Features.User.Card.Id),
	)

OnlineQueryParams.WithInput and OnlineQueryParams.WithOutputs are mandatory methods. This means they must each be called at least once for OnlineQueryParamsComplete to be returned. Otherwise, an incomplete type will be returned, and it cannot be passed into Client.OnlineQuery.

func (OnlineQueryParamsComplete) ToBytes added in v0.4.3 

func (p OnlineQueryParamsComplete) ToBytes(options ...*SerializationOptions) ([]byte, error)

func (OnlineQueryParamsComplete) WithBranchId added in v0.4.7 

func (p OnlineQueryParamsComplete) WithBranchId(branchId string) OnlineQueryParamsComplete

WithBranchId returns a copy of Online Query parameters with the specified branch id added. For use via method chaining. See OnlineQueryParamsComplete for usage examples.

func (OnlineQueryParamsComplete) WithInput 

func (p OnlineQueryParamsComplete) WithInput(feature any, value any) OnlineQueryParamsComplete

WithInput returns a copy of Online Query parameters with the specified input added. For use via method chaining. See OnlineQueryParamsComplete for usage examples.

func (OnlineQueryParamsComplete) WithInputs added in v0.17.1 

func (p OnlineQueryParamsComplete) WithInputs(inputs map[any]any) OnlineQueryParamsComplete

WithInputs returns a copy of Online Query parameters with the specified inputs added. For use via method chaining. See OnlineQueryParamsComplete for usage examples.

func (OnlineQueryParamsComplete) WithOutputs 

func (p OnlineQueryParamsComplete) WithOutputs(features ...any) OnlineQueryParamsComplete

WithOutputs returns a copy of Online Query parameters with the specified outputs added. For use via method chaining. See OnlineQueryParamsComplete for usage examples.

func (OnlineQueryParamsComplete) WithQueryName added in v0.14.0 

func (p OnlineQueryParamsComplete) WithQueryName(queryName string) OnlineQueryParamsComplete

WithQueryName returns a copy of Online Query parameters with the specified input added. For use via method chaining. See OnlineQueryParamsComplete for usage examples.

func (OnlineQueryParamsComplete) WithQueryNameVersion added in v0.14.0 

func (p OnlineQueryParamsComplete) WithQueryNameVersion(queryNameVersion string) OnlineQueryParamsComplete

WithQueryNameVersion returns a copy of Online Query parameters with the specified input added. For use via method chaining. See OnlineQueryParamsComplete for usage examples.

func (OnlineQueryParamsComplete) WithStaleness 

func (p OnlineQueryParamsComplete) WithStaleness(feature any, duration time.Duration) OnlineQueryParamsComplete

WithStaleness returns a copy of Online Query parameters with the specified staleness added. For use via method chaining. See OnlineQueryParamsComplete for usage examples. See https://docs.chalk.ai/docs/query-caching for more information on staleness.

func (OnlineQueryParamsComplete) WithTags added in v0.17.4 

func (p OnlineQueryParamsComplete) WithTags(tags ...string) OnlineQueryParamsComplete

WithTags returns a copy of Online Query parameters with the specified tags added. For use via method chaining. See OnlineQueryParamsComplete for usage examples.

type OnlineQueryResult 

type OnlineQueryResult struct {
	// The output features and any query metadata.
	Data []FeatureResult

	// Execution metadata for the query. See QueryMeta for details.
	Meta *QueryMeta
	// contains filtered or unexported fields
}

OnlineQueryResult holds the result of an online query.

func (*OnlineQueryResult) GetFeature 

func (result *OnlineQueryResult) GetFeature(feature any) (*FeatureResult, error)

GetFeature returns a wrapper for the raw, uncasted value of the specified feature. To get the value of a feature as its appropriate Go type, use the UnmarshalInto method.

func (*OnlineQueryResult) GetFeatureValue 

func (result *OnlineQueryResult) GetFeatureValue(feature any) (any, error)

GetFeatureValue returns the raw, uncasted value of the specified feature. To get the value of a feature as its appropriate Go type, use the UnmarshalInto method.

func (*OnlineQueryResult) UnmarshalInto 

func (result *OnlineQueryResult) UnmarshalInto(resultHolder any) (returnErr error)

UnmarshalInto unmarshals OnlineQueryResult.Data into the specified struct (passed by pointer). The input argument should be a pointer to the struct that represents the output namespace.

  1. UnmarshalInto populates fields corresponding to outputs specified in OnlineQueryParams, while leaving all other fields as nil. If the struct has fields that point to other structs (has-one relations), those nested structs will also be populated with their respective feature values.

  2. UnmarshalInto also errs if its argument is not a pointer to a struct.

Implicit usage example (pass result struct into OnlineQuery): 

func printUserDetails(chalkClient chalk.Client) {
	user := User{}
	chalkClient.OnlineQuery(
	    context.Background(),
	    chalk.OnlineQueryParams{}.WithOutputs(
		    Features.User.Family.Size,
		    Features.User.SocureScore
	    ).WithInput(Features.User.Id, 1),
	    &user,
	)

	fmt.Println("User family size: ", *user.Family.Size)
	fmt.Println("User Socure score: ", *user.SocureScore)
}

Equivalent explicit usage example: 

func printUserDetails(chalkClient chalk.Client) {
	result, _ := chalkClient.OnlineQuery(
	    context.Background(),
	    chalk.OnlineQueryParams{}.WithOutputs(
		    Features.User.Family.Size,
		    Features.User.SocureScore
	    ).WithInput(Features.User.Id, 1),
	    nil
	)

	user := User{}
	result.UnmarshalInto(&user)

	fmt.Println("User family size: ", *user.Family.Size)
	fmt.Println("User Socure score: ", *user.SocureScore)
}

To ensure fast unmarshals, see `WarmUpUnmarshaller`.

type QueryContext added in v0.20.2 

type QueryContext map[string]QueryContextValue

func NewQueryContext added in v0.20.2 

func NewQueryContext(m map[string]any) (*QueryContext, error)

func (*QueryContext) ToMap added in v0.20.2 

func (qc *QueryContext) ToMap() *map[string]any

type QueryContextValue added in v0.20.2 

type QueryContextValue interface {
	ToProto() (*structpb.Value, error)
	// contains filtered or unexported methods
}

type QueryMeta 

type QueryMeta struct {
	// Execution duration in seconds
	ExecutionDurationS float64 `json:"execution_duration_s"`

	// The id of the deployment that served this query.
	DeploymentId string `json:"deployment_id"`

	// The id of the environment that served this query. Not intended to be human-readable,
	// but helpful for support.
	EnvironmentId string `json:"environment_id"`

	// The short name of the environment that served this query. For example: "dev" or "prod".
	EnvironmentName string `json:"environment_name"`

	// A unique ID generated and persisted by Chalk for this query. All computed features,
	// metrics, and logs are associated with this ID. Your system can store this ID for
	// audit and debugging workflows.
	QueryId string `json:"query_id"`

	// At the start of query execution, Chalk computes 'datetime.now()'. This value is used
	// to timestamp computed features.
	QueryTimestamp *time.Time `json:"query_timestamp"`

	// Deterministic hash of the 'structure' of the query. Queries that have the same
	// input/output features will typically have the same hash; changes may be observed
	// over time as we adjust implementation details.
	QueryHash string `json:"query_hash"`
}

QueryMeta represents metadata about a Chalk query.

type QueryName added in v0.3.6 

type QueryName = string

type QueryStatus 

type QueryStatus int

QueryStatus represents the status of an offline query. 

const (
	// QueryStatusPendingSubmission to the database.
	QueryStatusPendingSubmission QueryStatus = 1

	// QueryStatusSubmitted to the database, but not yet running.
	QueryStatusSubmitted QueryStatus = 2

	// QueryStatusRunning in the database.
	QueryStatusRunning QueryStatus = 3

	// QueryStatusError with either submitting or running the job.
	QueryStatusError QueryStatus = 4

	// QueryStatusExpired indicates the job did not complete before an expiration
	// deadline, so there are no results.
	QueryStatusExpired QueryStatus = 5

	// QueryStatusCancelled indicates the job was manually cancelled before it
	// errored or finished successfully.
	QueryStatusCancelled QueryStatus = 6

	// QueryStatusSuccessful indicates the job successfully ran.
	QueryStatusSuccessful QueryStatus = 7
)

type ResolverException 

type ResolverException struct {
	// The name of the class of the exception.
	Kind string `json:"kind"`

	// The message taken from the exception.
	Message string `json:"message"`

	// The stacktrace produced by the code.
	Stacktrace string `json:"stacktrace"`
}

type ResourceRequests added in v1.2.69 

type ResourceRequests struct {
	// CPU requests (e.g., "8", "0.5", "500m" for millicore)
	CPU *string `json:"cpu,omitempty"`

	// Memory requests (e.g., "1G", "500M", "1000000000" bytes)
	Memory *string `json:"memory,omitempty"`

	// Ephemeral volume size for spilling intermediate state
	EphemeralVolumeSize *string `json:"ephemeral_volume_size,omitempty"`

	// Ephemeral storage size
	EphemeralStorage *string `json:"ephemeral_storage,omitempty"`

	// Resource group
	ResourceGroup *string `json:"resource_group,omitempty"`
}

ResourceRequests defines resource requirements for offline queries and cron jobs that run in isolated environments.

type RowResult added in v1.2.0 

type RowResult struct {
	Features map[string]FeatureOutput
}

func (*RowResult) GetFeature added in v1.2.0 

func (r *RowResult) GetFeature(feature any) (*FeatureOutput, error)

GetFeature takes in a feature string or a codegen'd feature reference and returns the `FeatureOutput` object. Given this codegen'd snippet: 

type User struct {
 	Id                       *int64
 	FullName                 *string
}

var Features struct {
 	User *User
}

func init() {
 	InitFeaturesErr = chalk.InitFeatures(&Features)
}

You would get the feature object for "user.full_name" as follows: 

feature, err := row.GetFeature(Features.User.FullName)

func (*RowResult) GetFeatureValue added in v1.2.0 

func (r *RowResult) GetFeatureValue(feature any) (any, error)

type SerializationOptions added in v0.5.1 

type SerializationOptions struct {
	ClientConfigBranchId string
	Allocator            memory.Allocator
	// contains filtered or unexported fields
}

type ServerError 

type ServerError struct {
	// The type of the error.
	Code ErrorCode `json:"code"`

	// The category of the error, given in the type field for the error codes.
	// This will be one of "REQUEST", "NETWORK", and "FIELD".
	Category ErrorCodeCategory `json:"category"`

	// A readable description of the error message.
	Message string `json:"message"`

	// The exception that caused the failure, if applicable.
	Exception *ResolverException `json:"exception"`

	// The fully qualified name of the failing feature, e.g. `user.identity.has_voip_phone`
	Feature string `json:"feature"`

	// The fully qualified name of the failing resolver, e.g. `my.project.get_fraud_score`.
	Resolver string `json:"resolver"`
}

ServerError is an error that occurred in Chalk's server, for example, when a resolver unexpectedly fails to run.

func (*ServerError) Error 

func (e *ServerError) Error() string

type StdOutLeveledLogger 

type StdOutLeveledLogger struct {
	// Level is the minimum logging level that will be emitted by this logger.
	//
	// For example, a Level set to LevelWarn will emit warnings and errors, but
	// not informational or debug messages.
	//
	// Always set this with a constant like LevelWarn because the individual
	// values are not guaranteed to be stable.
	Level Level
	// contains filtered or unexported fields
}

StdOutLeveledLogger is a leveled logger implementation.

It prints warnings and errors to `os.Stderr` and other messages to `os.Stdout`.

func (*StdOutLeveledLogger) Debugf 

func (l *StdOutLeveledLogger) Debugf(format string, v ...interface{})

Debugf logs a debug message using Printf conventions.

func (*StdOutLeveledLogger) Errorf 

func (l *StdOutLeveledLogger) Errorf(format string, v ...interface{})

Errorf logs a warning message using Printf conventions.

func (*StdOutLeveledLogger) Infof 

func (l *StdOutLeveledLogger) Infof(format string, v ...interface{})

Infof logs an informational message using Printf conventions.

func (*StdOutLeveledLogger) Warnf 

func (l *StdOutLeveledLogger) Warnf(format string, v ...interface{})

Warnf logs a warning message using Printf conventions.

type StringValue added in v0.20.2 

type StringValue string

func (StringValue) ToProto added in v0.20.2 

func (v StringValue) ToProto() (*structpb.Value, error)

type TokenResult added in v0.13.9 

type TokenResult struct {
	// The access token that can be used to authenticate requests to the Chalk API.
	AccessToken string `json:"access_token"`

	// The primary environment that the token is scoped to.
	PrimaryEnvironment string `json:"primary_environment"`

	// The time at which the token expires.
	ValidUntil time.Time `json:"valid_until"`

	// The GRPC endpoint for the engine.
	Engines map[string]string `json:"engines"`
}

TokenResult holds the result of a GetToken request.

type TriggerResolverRunParams 

type TriggerResolverRunParams struct {
	// ResolverFqn is the fully qualified name of the offline resolver to trigger.
	ResolverFqn string `json:"resolver_fqn"`

	// EnvironmentId is the environment under which you'd like to query your data.
	EnvironmentId string `json:"environment_id"`

	// PreviewDeploymentId, if specified, will be used by Chalk to route
	// your request to the relevant preview deployment.
	PreviewDeploymentId string `json:"preview_deployment_id"`
}

type TriggerResolverRunResult 

type TriggerResolverRunResult struct {
	// Id is the ID of the offline resolver run.
	Id string `json:"id"`

	// Status is the current status of the resolver run.
	Status string `json:"status"`
}

type TsFeatureValue 

type TsFeatureValue struct {
	// The value of the feature. In the context of offline query,
	// this is always a value of a primary feature.
	Value any

	// The observation time at which you would like the output
	// feature values to be queried. If nil, [OfflineQueryParams.DefaultTime]
	// will be used as the observation time. If [OfflineQueryParams.DefaultTime]
	// is also nil, the current time will be used as the observation time.
	ObservationTime *time.Time
}

TsFeatureValue is a struct that can be passed to OfflineQueryParams.WithInput to specify the value of a feature along with a timestamp. This timestamp indicates the observation time at which you would like the output feature values to be queried. For more information about observation time, see Temporal Consistency.

type UpdateAggregatesParams added in v0.14.0 

type UpdateAggregatesParams struct {
	// Inputs is a map of features to values. The features should
	// either be a string or codegen-ed Feature object. The values
	// should be a slice of the appropriate type. All slices should
	// be the same length as the number of entities you want to upload
	// features for.
	Inputs map[any]any

	Context context.Context
}

UpdateAggregatesParams lets you specify parameters for updating aggregated values of your windowed aggregation features.

type UpdateAggregatesResult added in v0.14.0 

type UpdateAggregatesResult struct {
	TraceId string `json:"trace_id"`
}

UpdateAggregatesResult holds the result of an upload aggregates request.

type UploadFeaturesParams added in v0.3.13 

type UploadFeaturesParams struct {
	// Inputs is a map of features to values. The features should
	// either be a string or codegen-ed Feature object. The values
	// should be a slice of the appropriate type. All slices should
	// be the same length as the number of entities you want to upload
	// features for.
	Inputs map[any]any

	// EnvironmentOverride is the environment to which you want to upload
	// features. If not specified, defaults to the environment specified
	// in the client configuration.
	EnvironmentOverride string

	// PreviewDeploymentId is the preview deployment to which you want to upload
	// features. If not specified, defaults to the main deployment.
	PreviewDeploymentId string
}

UploadFeaturesParams defines the parameters that help you execute an upload features request.

type UploadFeaturesResult added in v0.3.13 

type UploadFeaturesResult struct {
	OperationId string `json:"operation_id"`
}

UploadFeaturesResult holds the result of an upload features request.

Source Files

View all Source files

Directories

Path Synopsis
gen module
auth
colls
ptr
sketches
tests
tests/benchmark
tests/fixtures
tests/integration
pkg
errors

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.