Getting Started
This page walks through installing Ferret as a Go dependency, running a query, and working with the result.
Installation
From your Go application module, install Ferret Core v2.0.0-alpha.62. This release requires Go 1.26 or later. For a new application, run go mod init example.com/myapp first.
$go get github.com/MontFerret/ferret/v2@v2.0.0-alpha.62
For an existing integration, follow the consumable output migration and the Encoding API migration.
Running a query
The simplest way to execute a query is engine.Run. It compiles the source, runs it in a fresh session, and returns a one-shot output handle. Collect it to obtain owned encoded bytes.
package main
import (
"context"
"errors"
"fmt"
"log"
"github.com/MontFerret/ferret/v2"
)
func main() {
if err := run(); err != nil {
log.Fatal(err)
}
}
func run() (err error) {
engine, err := ferret.New()
if err != nil {
return err
}
defer func() { err = errors.Join(err, engine.Close()) }()
output, err := engine.Run(
context.Background(),
ferret.NewAnonymousSource(`return { name: "Ferret", version: 2 }`),
)
if err != nil {
return err
}
defer func() { err = errors.Join(err, output.Close()) }()
content, err := output.Collect(context.Background())
if err != nil {
return err
}
fmt.Println(string(content.Data))
// {"name":"Ferret","version":2}
return nil
}
ferret.NewAnonymousSource is convenient for one-shot queries. Use ferret.NewSource(name, content) when the source name should appear in compilation errors and debugger output. Both constructors return ferret.Source values.
Native applications normally use the root ferret package for sources, engine and session options, log levels, module contracts, parameter values, program formats, and output. Import a package under pkg only when using the specialized API owned by that package.
Compiling and reusing a plan
When the same query runs many times — with different parameters, in different goroutines, or on a schedule — compile it once and create sessions from the resulting plan:
plan, err := engine.Compile(ctx,
ferret.NewSource("greeting.fql", `return upper(@name)`),
)
if err != nil {
return err
}
defer plan.Close()
names := []string{"alice", "bob", "carol"}
// This snippet also imports "errors".
for _, name := range names {
session, err := plan.NewSession(ctx,
ferret.WithSessionParam("name", name),
)
if err != nil {
return err
}
output, err := session.Run(ctx)
if err != nil {
return errors.Join(err, session.Close())
}
content, collectErr := output.Collect(ctx)
closeErr := errors.Join(output.Close(), session.Close())
if err := errors.Join(collectErr, closeErr); err != nil {
return err
}
fmt.Println(string(content.Data))
}
// "ALICE"
// "BOB"
// "CAROL"
The plan manages an internal pool of virtual machines. Sessions borrow a VM from the pool and return it on close, so creating many sessions from the same plan is efficient.
Passing parameters
Parameters let the host application inject values into a query at runtime. In FQL, parameters are referenced with the @ prefix.
Engine-level parameters apply to every session:
engine, err := ferret.New(
ferret.WithParam("base_url", "https://api.example.com"),
)
Session-level parameters override engine defaults for a single execution:
session, err := plan.NewSession(ctx,
ferret.WithSessionParam("user_id", 42),
ferret.WithSessionParam("base_url", "https://staging.example.com"),
)
You can inspect which parameters a compiled query declares:
params := plan.Params()
fmt.Println(params)
// [name] for greeting.fql
See Parameters for the full parameter API.
Handling errors
Ferret returns standard Go errors. Compilation errors include source location information:
_, err := engine.Compile(ctx,
ferret.NewSource("bad.fql", `return @`),
)
if err != nil {
fmt.Println(err)
// compilation error with line and column
}
Preparation failures are returned by Run. Once execution enters the VM, execution, encoding, hooks, and output cleanup failures are reported by Collect or Consume:
output, err := session.Run(ctx)
if err != nil {
return err // preparation failed
}
defer output.Close()
content, err := output.Collect(ctx)
if err != nil {
// Inspect available content independently, then handle the terminal error.
return err
}
_ = content
Context cancellation and timeouts work as expected:
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
output, err := session.Run(ctx)
if err != nil {
return err // cancellation may prevent VM admission
}
defer output.Close()
_, err = output.Collect(ctx)
if err != nil {
// errors.Is(err, context.DeadlineExceeded) detects an expired deadline.
return err
}
Keep the original Run context alive until output consumption completes. A new consumption context cannot revive a canceled invocation. See Output for borrowing, cancellation, and closure.
The VM observes cancellation at structural execution boundaries rather than polling every native operation. Blocking host functions, iterators, queries, streams, and other context-aware capabilities receive this same context and must observe it while they retain control. Cancellation and deadline errors propagate to the caller and cannot be suppressed by FQL error recovery.
Next steps
Results
Output
Collect owned content or consume borrowed bytes, and settle terminal failures.
Execution
Executing Ferret
Use the Go Engine, Plan, and Session lifecycle.
Runtime modules
Modules
Install, configure, register, and manage modules in an embedded runtime.
Host functions
Custom Functions
Register Go functions and namespaces that scripts can call.
Runtime setup
Runtime Configuration
Control the standard library, logging, encoding, concurrency, and file system access.