Categorygithub.com/chalk-ai/chalk-go
modulepackage
0.17.18
Repository: https://github.com/chalk-ai/chalk-go.git
Documentation: pkg.go.dev

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

With overrides

client, err := chalk.NewClient(&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, set the UseGrpc field in ClientConfig to true.

client, err := chalk.NewClient(&chalk.ClientConfig{
    UseGrpc: true,
})

You can then make requests just like you would without UseGrpc specified.

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

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(
    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(
    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(
    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(&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.

# Packages

No description provided by the author

# Functions

No description provided by the author
No description provided by the author
No description provided by the author
NewClient creates a Client with authentication settings configured.
No description provided by the author
NewGRPCClient creates a GRPCClient with authentication settings configured.
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
UnmarshalTableInto unmarshals the given Arrow table into the given result holders.
No description provided by the author

# Constants

No description provided by the author
No description provided by the author
No description provided by the author
LevelDebug sets a logger to show informational messages or anything more severe.
LevelError sets a logger to show error messages only.
LevelInfo sets a logger to show informational messages or anything more severe.
LevelNull sets a logger to show no messages at all.
LevelWarn sets a logger to show warning messages or anything more severe.
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
QueryStatusCancelled indicates the job was manually cancelled before it errored or finished successfully.
QueryStatusError with either submitting or running the job.
QueryStatusExpired indicates the job did not complete before an expiration deadline, so there are no results.
QueryStatusPendingSubmission to the database.
QueryStatusRunning in the database.
QueryStatusSubmitted to the database, but not yet running.
QueryStatusSuccessful indicates the job successfully ran.
No description provided by the author

# Variables

Cancelled indicates the operation was cancelled, typically by the caller.
DeadlineExceeded indicates the deadline expired before the operation could complete.
DefaultLeveledLogger is the default logger that the library will use to log errors, warnings, and informational messages.
Field errors are raised while running a feature resolver for a particular field.
No description provided by the author
InternalServerError indicates an unspecified error occurred.
InvalidQuery indicates the query is invalid.
Network errors are thrown outside your resolvers.
ParseFailed indicates the query contained features that do not exist.
Request errors are raised before execution of your resolver code.
ResolverFailed indicates the resolver for a feature errored.
ResolverNotFound indicates a resolver was required as part of running the dependency graph that could not be found.
ResolverTimedOut indicates the resolver for a feature timed out.
Unauthenticated indicates the request was submitted with an invalid authentication header.
Unauthorized indicates the supplied credentials do not provide the right authorization to execute the request.
UpstreamFailed indicates a crash in a resolver that was to produce an input for the resolver crashed, and so the resolver could not run.
ValidationFailed indicates a feature value did not match the expected schema (e.g.

# Structs

No description provided by the author
No description provided by the author
ClientError is an error that occurred in Client or its dependencies.
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
ErrorCode indicates the type of error occurred.
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
HTTPError is a wrapper around a standard HTTP error such as missing authorization.
OfflineQueryParams defines the parameters that help you execute an online query.
OfflineQueryParamsComplete is the only type of object accepted as an argument to Client.OfflineQuery.
No description provided by the author
OnlineQueryBulkResult holds the result of a bulk online query.
OnlineQueryParams defines the parameters that help you execute an online query.
OnlineQueryParamsComplete is the only type of object accepted as an argument to Client.OnlineQuery.
OnlineQueryResult holds the result of an online query.
QueryMeta represents metadata about a Chalk query.
No description provided by the author
No description provided by the author
ServerError is an error that occurred in Chalk's server, for example, when a resolver unexpectedly fails to run.
StdOutLeveledLogger is a leveled logger implementation.
TokenResult holds the result of a GetToken request.
No description provided by the author
No description provided by the author
TsFeatureValue is a struct that can be passed to OfflineQueryParams.WithInput to specify the value of a feature along with a timestamp.
UpdateAggregatesParams lets you specify parameters for updating aggregated values of your windowed aggregation features.
UpdateAggregatesResult holds the result of an upload aggregates request.
UploadFeaturesParams defines the parameters that help you execute an upload features request.
UploadFeaturesResult holds the result of an upload features request.

# Interfaces

Client is the primary interface for interacting with Chalk.
GRPCClient is the gRPC-native interface for interacting with Chalk.
No description provided by the author
LeveledLogger provides a basic leveled logging interface for printing debug, informational, warning, and error messages.

# Type aliases

No description provided by the author
No description provided by the author
No description provided by the author
Level represents a logging level.
No description provided by the author
No description provided by the author
QueryStatus represents the status of an offline query.