# Design
Source: https://docs.hypermode.com/badger/design

Architected for fast key-value storage in Go

We wrote Badger with these design goals in mind:

* Write a key-value database in pure Go
* Use latest research to build the fastest KV database for data sets spanning
  terabytes
* Optimize for modern storage devices

Badger’s design is based on a paper titled
[WiscKey: Separating Keys from Values in SSD-conscious Storage](https://www.usenix.org/system/files/conference/fast16/fast16-papers-lu.pdf).

## References

The following blog posts are a great starting point for learning more about
Badger and the underlying design principles:

* [Introducing Badger: A fast key-value store written natively in Go](https://dgraph.io/blog/post/badger/)
* [Make Badger crash resilient with ALICE](https://dgraph.io/blog/post/alice/)
* [Badger vs LMDB vs BoltDB: Benchmarking key-value databases in Go](https://dgraph.io/blog/post/badger-lmdb-boltdb/)
* [Concurrent ACID Transactions in Badger](https://dgraph.io/blog/post/badger-txn/)

## Comparisons

| Feature                       | Badger                                 | RocksDB                      | BoltDB  |
| ----------------------------- | -------------------------------------- | ---------------------------- | ------- |
| Design                        | LSM tree with value log                | LSM tree only                | B+ tree |
| High Read throughput          | Yes                                    | No                           | Yes     |
| High Write throughput         | Yes                                    | Yes                          | No      |
| Designed for SSDs             | Yes (with latest research<sup>1</sup>) | Not specifically<sup>2</sup> | No      |
| Embeddable                    | Yes                                    | Yes                          | Yes     |
| Sorted KV access              | Yes                                    | Yes                          | Yes     |
| Pure Go (no Cgo)              | Yes                                    | No                           | Yes     |
| Transactions                  | Yes                                    | Yes                          | Yes     |
| ACID-compliant                | Yes, concurrent with SSI<sup>3</sup>   | No                           | Yes     |
| Snapshots                     | Yes                                    | Yes                          | Yes     |
| TTL support                   | Yes                                    | Yes                          | No      |
| 3D access (key-value-version) | Yes<sup>4</sup>                        | No                           | No      |

<sup>1</sup> The WiscKey paper (on which Badger is based) saw big wins with
separating values from keys, significantly reducing the write amplification
compared to a typical LSM tree.

<sup>2</sup> RocksDB is an SSD-optimized version of LevelDB, which was designed
specifically for rotating disks. As such RocksDB's design isn't aimed at SSDs.

<sup>3</sup> SSI: Serializable Snapshot Isolation. For more details, see the
blog post [Concurrent ACID Transactions in
Badger](https://dgraph.io/blog/post/badger-txn/)

<sup>4</sup> Badger provides direct access to value versions via its Iterator
API. Users can also specify how many versions to keep per key via Options.

## Benchmarks

We've run comprehensive benchmarks against RocksDB, BoltDB, and LMDB. The
benchmarking code with detailed logs are in the
[badger-bench](https://github.com/dgraph-io/badger-bench) repo.


# Overview
Source: https://docs.hypermode.com/badger/overview

Welcome to the Badger docs!

## What is Badger? {/* <!-- vale Google.Contractions = NO --> */}

BadgerDB is an embeddable, persistent, and fast key-value (KV) database written
in pure Go. It's the underlying database for [Dgraph](https://dgraph.io), a
fast, distributed graph database. It's meant to be an efficient alternative to
non-Go-based key-value stores like RocksDB.

## Changelog

We keep the
[repo Changelog](https://github.com/hypermodeinc/badger/blob/main/CHANGELOG.md)
up to date with each release.


# Quickstart
Source: https://docs.hypermode.com/badger/quickstart

Everything you need to get started with Badger

## Prerequisites

* [Go](https://go.dev/doc/install) - v1.23 or higher
* Text editor - we recommend [VS Code](https://code.visualstudio.com/)
* Terminal - access Badger through a command-line interface (CLI)

## Installing

To start using Badger, run the following command to retrieve the library.

```sh
go get github.com/dgraph-io/badger/v4
```

Then, install the Badger command line utility into your `$GOBIN` path.

```sh
go install github.com/dgraph-io/badger/v4/badger@latest
```

## Opening a database

The top-level object in Badger is a `DB`. It represents multiple files on disk
in specific directories, which contain the data for a single database.

To open your database, use the `badger.Open()` function, with the appropriate
options. The `Dir` and `ValueDir` options are mandatory and you must specify
them in your client. To simplify, you can set both options to the same value.

<Note>
  Badger obtains a lock on the directories. Multiple processes can't open the
  same database at the same time.
</Note>

```go
package main

import (
  "log"

  badger "github.com/dgraph-io/badger/v4"
)

func main() {
  // Open the Badger database located in the /tmp/badger directory.
  // It will be created if it doesn't exist.
  db, err := badger.Open(badger.DefaultOptions("/tmp/badger"))
  if err != nil {
    log.Fatal(err)
  }

  defer db.Close()

  // your code here
}
```

### In-memory/diskless mode

By default, Badger ensures all data persists to disk. It also supports a pure
in-memory mode. When Badger is running in this mode, all data remains in memory
only. Reads and writes are much faster, but Badger loses all stored data in the
case of a crash or close. To open badger in in-memory mode, set the `InMemory`
option.

```go
opt := badger.DefaultOptions("").WithInMemory(true)
```

### Encryption mode

If you enable encryption in Badger, you also need to set the index cache size.

<Tip>
  The cache improves the performance. Otherwise, reads can be very slow with
  encryption enabled.
</Tip>

For example, to set a `100 Mb` cache:

```go
opts.IndexCache = 100 << 20 // 100 mb or some other size based on the amount of data
```

## Transactions

### Read-only transactions

To start a read-only transaction, you can use the `DB.View()` method:

```go
err := db.View(func(txn *badger.Txn) error {
  // your code here

  return nil
})
```

You can't perform any writes or deletes within this transaction. Badger ensures
that you get a consistent view of the database within this closure. Any writes
that happen elsewhere after the transaction has started aren't seen by calls
made within the closure.

### Read-write transactions

To start a read-write transaction, you can use the `DB.Update()` method:

```go
err := db.Update(func(txn *badger.Txn) error {
  // Your code here…
  return nil
})
```

Badger allows all database operations inside a read-write transaction.

Always check the returned error value. If you return an error within your
closure it's passed through.

An `ErrConflict` error is reported in case of a conflict. Depending on the state
of your app, you have the option to retry the operation if you receive this
error.

An `ErrTxnTooBig` is reported in case the number of pending writes/deletes in
the transaction exceeds a certain limit. In that case, it's best to commit the
transaction and start a new transaction immediately. Here is an example (we
aren't checking for errors in some places for simplicity):

```go
updates := make(map[string]string)
txn := db.NewTransaction(true)
for k,v := range updates {
  if err := txn.Set([]byte(k),[]byte(v)); err == badger.ErrTxnTooBig {
    _ = txn.Commit()
    txn = db.NewTransaction(true)
    _ = txn.Set([]byte(k),[]byte(v))
  }
}
_ = txn.Commit()
```

### Managing transactions manually

The `DB.View()` and `DB.Update()` methods are wrappers around the
`DB.NewTransaction()` and `Txn.Commit()` methods (or `Txn.Discard()` in case of
read-only transactions). These helper methods start the transaction, execute a
function, and then safely discard your transaction if an error is returned. This
is the recommended way to use Badger transactions.

However, sometimes you may want to manually create and commit your transactions.
You can use the `DB.NewTransaction()` function directly, which takes in a
boolean argument to specify whether a read-write transaction is required. For
read-write transactions, it's necessary to call `Txn.Commit()` to ensure the
transaction is committed. For read-only transactions, calling `Txn.Discard()` is
sufficient. `Txn.Commit()` also calls `Txn.Discard()` internally to cleanup the
transaction, so just calling `Txn.Commit()` is sufficient for read-write
transaction. However, if your code doesn’t call `Txn.Commit()` for some reason
(for e.g it returns prematurely with an error), then please make sure you call
`Txn.Discard()` in a `defer` block. Refer to the code below.

```go
// Start a writable transaction.
txn := db.NewTransaction(true)
defer txn.Discard()

// Use the transaction...
err := txn.Set([]byte("answer"), []byte("42"))
if err != nil {
    return err
}

// Commit the transaction and check for error.
if err := txn.Commit(); err != nil {
    return err
}
```

The first argument to `DB.NewTransaction()` is a boolean stating if the
transaction should be writable.

Badger allows an optional callback to the `Txn.Commit()` method. Normally, the
callback can be set to `nil`, and the method will return after all the writes
have succeeded. However, if this callback is provided, the `Txn.Commit()` method
returns as soon as it has checked for any conflicts. The actual writing to the
disk happens asynchronously, and the callback is invoked once the writing has
finished, or an error has occurred. This can improve the throughput of the app
in some cases. But it also means that a transaction isn't durable until the
callback has been invoked with a `nil` error value.

## Using key/value pairs

To save a key/value pair, use the `Txn.Set()` method:

```go
err := db.Update(func(txn *badger.Txn) error {
  err := txn.Set([]byte("answer"), []byte("42"))
  return err
})
```

Key/Value pair can also be saved by first creating `Entry`, then setting this
`Entry` using `Txn.SetEntry()`. `Entry` also exposes methods to set properties
on it.

```go
err := db.Update(func(txn *badger.Txn) error {
  e := badger.NewEntry([]byte("answer"), []byte("42"))
  err := txn.SetEntry(e)
  return err
})
```

This sets the value of the `"answer"` key to `"42"`. To retrieve this value, we
can use the `Txn.Get()` method:

```go
err := db.View(func(txn *badger.Txn) error {
  item, err := txn.Get([]byte("answer"))
  handle(err)

  var valNot, valCopy []byte
  err := item.Value(func(val []byte) error {
    // This func with val would only be called if item.Value encounters no error.

    // Accessing val here is valid.
    fmt.Printf("The answer is: %s\n", val)

    // Copying or parsing val is valid.
    valCopy = append([]byte{}, val...)

    // Assigning val slice to another variable is NOT OK.
    valNot = val // Do not do this.
    return nil
  })
  handle(err)

  // DO NOT access val here. It is the most common cause of bugs.
  fmt.Printf("NEVER do this. %s\n", valNot)

  // You must copy it to use it outside item.Value(...).
  fmt.Printf("The answer is: %s\n", valCopy)

  // Alternatively, you could also use item.ValueCopy().
  valCopy, err = item.ValueCopy(nil)
  handle(err)
  fmt.Printf("The answer is: %s\n", valCopy)

  return nil
})
```

`Txn.Get()` returns `ErrKeyNotFound` if the value isn't found.

Please note that values returned from `Get()` are only valid while the
transaction is open. If you need to use a value outside of the transaction then
you must use `copy()` to copy it to another byte slice.

Use the `Txn.Delete()` method to delete a key.

## Monotonically increasing integers

To get unique monotonically increasing integers with strong durability, you can
use the `DB.GetSequence` method. This method returns a `Sequence` object, which
is thread-safe and can be used concurrently via various goroutines.

Badger would lease a range of integers to hand out from memory, with the
bandwidth provided to `DB.GetSequence`. The frequency at which disk writes are
done is determined by this lease bandwidth and the frequency of `Next`
invocations. Setting a bandwidth too low would do more disk writes, setting it
too high would result in wasted integers if Badger is closed or crashes. To
avoid wasted integers, call `Release` before closing Badger.

```go
seq, err := db.GetSequence(key, 1000)
defer seq.Release()
for {
  num, err := seq.Next()
}
```

## Merge operations

Badger provides support for ordered merge operations. You can define a func of
type `MergeFunc` which takes in an existing value, and a value to be *merged*
with it. It returns a new value which is the result of the *merge* operation.
All values are specified in byte arrays. For e.g., here is a merge function
(`add`) which appends a `[]byte` value to an existing `[]byte` value.

```go
// Merge function to append one byte slice to another
func add(originalValue, newValue []byte) []byte {
  return append(originalValue, newValue...)
}
```

This function can then be passed to the `DB.GetMergeOperator()` method, along
with a key, and a duration value. The duration specifies how often the merge
function is run on values that have been added using the `MergeOperator.Add()`
method.

`MergeOperator.Get()` method can be used to retrieve the cumulative value of the
key associated with the merge operation.

```go
key := []byte("merge")

m := db.GetMergeOperator(key, add, 200*time.Millisecond)
defer m.Stop()

m.Add([]byte("A"))
m.Add([]byte("B"))
m.Add([]byte("C"))

res, _ := m.Get() // res should have value ABC encoded
```

Example: merge operator which increments a counter

```go
func uint64ToBytes(i uint64) []byte {
  var buf [8]byte
  binary.BigEndian.PutUint64(buf[:], i)
  return buf[:]
}

func bytesToUint64(b []byte) uint64 {
  return binary.BigEndian.Uint64(b)
}

// Merge function to add two uint64 numbers
func add(existing, new []byte) []byte {
  return uint64ToBytes(bytesToUint64(existing) + bytesToUint64(new))
}
```

It can be used as

```go
key := []byte("merge")

m := db.GetMergeOperator(key, add, 200*time.Millisecond)
defer m.Stop()

m.Add(uint64ToBytes(1))
m.Add(uint64ToBytes(2))
m.Add(uint64ToBytes(3))

res, _ := m.Get() // res should have value 6 encoded
```

## Setting time to live (TTL) and user metadata on keys

Badger allows setting an optional Time to Live (TTL) value on keys. Once the TTL
has elapsed, the key is no longer retrievable and is eligible for garbage
collection. A TTL can be set as a `time.Duration` value using the
`Entry.WithTTL()` and `Txn.SetEntry()` API methods.

```go
err := db.Update(func(txn *badger.Txn) error {
  e := badger.NewEntry([]byte("answer"), []byte("42")).WithTTL(time.Hour)
  err := txn.SetEntry(e)
  return err
})
```

An optional user metadata value can be set on each key. A user metadata value is
represented by a single byte. It can be used to set certain bits along with the
key to aid in interpreting or decoding the key-value pair. User metadata can be
set using `Entry.WithMeta()` and `Txn.SetEntry()` API methods.

```go
err := db.Update(func(txn *badger.Txn) error {
  e := badger.NewEntry([]byte("answer"), []byte("42")).WithMeta(byte(1))
  err := txn.SetEntry(e)
  return err
})
```

`Entry` APIs can be used to add the user metadata and TTL for same key. This
`Entry` then can be set using `Txn.SetEntry()`.

```go
err := db.Update(func(txn *badger.Txn) error {
  e := badger.NewEntry([]byte("answer"), []byte("42")).WithMeta(byte(1)).WithTTL(time.Hour)
  err := txn.SetEntry(e)
  return err
})
```

## Iterating over keys

To iterate over keys, we can use an `Iterator`, which can be obtained using the
`Txn.NewIterator()` method. Iteration happens in byte-wise lexicographical
sorting order.

```go
err := db.View(func(txn *badger.Txn) error {
  opts := badger.DefaultIteratorOptions
  opts.PrefetchSize = 10
  it := txn.NewIterator(opts)
  defer it.Close()
  for it.Rewind(); it.Valid(); it.Next() {
    item := it.Item()
    k := item.Key()
    err := item.Value(func(v []byte) error {
      fmt.Printf("key=%s, value=%s\n", k, v)
      return nil
    })
    if err != nil {
      return err
    }
  }
  return nil
})
```

The iterator allows you to move to a specific point in the list of keys and move
forward or backward through the keys one at a time.

By default, Badger prefetches the values of the next 100 items. You can adjust
that with the `IteratorOptions.PrefetchSize` field. However, setting it to a
value higher than `GOMAXPROCS` (which we recommend to be 128 or higher)
shouldn’t give any additional benefits. You can also turn off the fetching of
values altogether. See section below on key-only iteration.

### Prefix scans

To iterate over a key prefix, you can combine `Seek()` and `ValidForPrefix()`:

```go
db.View(func(txn *badger.Txn) error {
  it := txn.NewIterator(badger.DefaultIteratorOptions)
  defer it.Close()
  prefix := []byte("1234")
  for it.Seek(prefix); it.ValidForPrefix(prefix); it.Next() {
    item := it.Item()
    k := item.Key()
    err := item.Value(func(v []byte) error {
      fmt.Printf("key=%s, value=%s\n", k, v)
      return nil
    })
    if err != nil {
      return err
    }
  }
  return nil
})
```

### Possible pagination implementation using Prefix scans

Considering that iteration happens in **byte-wise lexicographical sorting**
order, it's possible to create a sorting-sensitive key. For example, a simple
blog post key might look like:`feed:userUuid:timestamp:postUuid`. Here, the
`timestamp` part of the key is treated as an attribute, and items will be stored
in the corresponding order:

| Order ASC | Key                                                           |
| :-------: | :------------------------------------------------------------ |
|     1     | feed:tQpnEDVRoCxTFQDvyQEzdo:1733127889:tQpnEDVRoCxTFQDvyQEzdo |
|     2     | feed:tQpnEDVRoCxTFQDvyQEzdo:1733127533:1Mryrou1xoekEaxzrFiHwL |
|     3     | feed:tQpnEDVRoCxTFQDvyQEzdo:1733127486:pprRrNL2WP4yfVXsSNBSx6 |

It's important to properly configure keys for lexicographical sorting to avoid
incorrect ordering.

A **prefix scan** through the preceding keys can be achieved using the prefix
`feed:tQpnEDVRoCxTFQDvyQEzdo`. All matching keys are returned, sorted by
`timestamp`.\
Sorting can be done in ascending or descending order based on `timestamp` or
`reversed timestamp` as needed:

```go
reversedTimestamp := math.MaxInt64-time.Now().Unix()
```

This makes it possible to implement simple pagination by using a limit for the
number of keys and a cursor (the last key from the previous iteration) to
identify where to resume.

```go
// startCursor may look like 'feed:tQpnEDVRoCxTFQDvyQEzdo:1733127486'.
// A prefix scan with this cursor will locate the specific key where
// the previous iteration stopped.
err = db.badger.View(func(txn *badger.Txn) error {
        it := txn.NewIterator(opts)
        defer it.Close()

        // Prefix example 'feed:tQpnEDVRoCxTFQDvyQEzdo'
        // if no cursor provided prefix scan starts from the beginning
        p := prefix
        if startCursor != nil {
             p = startCursor
        }
        iterNum := 0 // Tracks the number of iterations to enforce the limit.
        for it.Seek(p); it.ValidForPrefix(p); it.Next() {
            // The method it.ValidForPrefix ensures that iteration continues
            // as long as keys match the prefix.
            // For example, if p = 'feed:tQpnEDVRoCxTFQDvyQEzdo:1733127486',
            // it matches keys like
            // 'feed:tQpnEDVRoCxTFQDvyQEzdo:1733127889:pprRrNL2WP4yfVXsSNBSx6'.

            // Once the starting point for iteration is found, revert the prefix
            // back to 'feed:tQpnEDVRoCxTFQDvyQEzdo' to continue iterating sequentially.
            // Otherwise, iteration would stop after a single prefix-key match.
            p = prefix

            item := it.Item()
            key := string(item.Key())

            if iterNum > limit { // Limit reached.
                nextCursor = key // Save the next cursor for future iterations.
                return nil
            }
            iterNum++ // Increment iteration count.

            err := item.Value(func(v []byte) error {
                fmt.Printf("key=%s, value=%s\n", k, v)
                return nil
            })
            if err != nil {
                return err
            }
        }
        // If the number of iterations is less than the limit,
        // it means there are no more items for the prefix.
        if iterNum < limit {
            nextCursor = ""
        }
        return nil
    })
return nextCursor, err
```

### Key-only iteration

Badger supports a unique mode of iteration called *key-only* iteration. It's
several order of magnitudes faster than regular iteration, because it involves
access to the LSM-tree only, which is usually resident entirely in RAM. To
enable key-only iteration, you need to set the `IteratorOptions.PrefetchValues`
field to `false`. This can also be used to do sparse reads for selected keys
during an iteration, by calling `item.Value()` only when required.

```go
err := db.View(func(txn *badger.Txn) error {
  opts := badger.DefaultIteratorOptions
  opts.PrefetchValues = false
  it := txn.NewIterator(opts)
  defer it.Close()
  for it.Rewind(); it.Valid(); it.Next() {
    item := it.Item()
    k := item.Key()
    fmt.Printf("key=%s\n", k)
  }
  return nil
})
```

## Stream

Badger provides a Stream framework, which concurrently iterates over all or a
portion of the DB, converting data into custom key-values, and streams it out
serially to be sent over network, written to disk, or even written back to
Badger. This is a lot faster way to iterate over Badger than using a single
Iterator. Stream supports Badger in both managed and normal mode.

Stream uses the natural boundaries created by SSTables within the LSM tree, to
quickly generate key ranges. Each goroutine then picks a range and runs an
iterator to iterate over it. Each iterator iterates over all versions of values
and is created from the same transaction, thus working over a snapshot of the
DB. Every time a new key is encountered, it calls `ChooseKey(item)`, followed by
`KeyToList(key, itr)`. This allows a user to select or reject that key, and if
selected, convert the value versions into custom key-values. The goroutine
batches up 4 MB worth of key-values, before sending it over to a channel.
Another goroutine further batches up data from this channel using *smart
batching* algorithm and calls `Send` serially.

This framework is designed for high throughput key-value iteration, spreading
the work of iteration across many goroutines. `DB.Backup` uses this framework to
provide full and incremental backups quickly. Dgraph is a heavy user of this
framework. In fact, this framework was developed and used within Dgraph, before
getting ported over to Badger.

```go
stream := db.NewStream()
// db.NewStreamAt(readTs) for managed mode.

// -- Optional settings
stream.NumGo = 16                     // Set number of goroutines to use for iteration.
stream.Prefix = []byte("some-prefix") // Leave nil for iteration over the whole DB.
stream.LogPrefix = "Badger.Streaming" // For identifying stream logs. Outputs to Logger.

// ChooseKey is called concurrently for every key. If left nil, assumes true by default.
stream.ChooseKey = func(item *badger.Item) bool {
  return bytes.HasSuffix(item.Key(), []byte("er"))
}

// KeyToList is called concurrently for chosen keys. This can be used to convert
// Badger data into custom key-values. If nil, uses stream.ToList, a default
// implementation, which picks all valid key-values.
stream.KeyToList = nil

// -- End of optional settings.

// Send is called serially, while Stream.Orchestrate is running.
stream.Send = func(list *pb.KVList) error {
  return proto.MarshalText(w, list) // Write to w.
}

// Run the stream
if err := stream.Orchestrate(context.Background()); err != nil {
  return err
}
// Done.
```

## Garbage collection

Badger values need to be garbage collected, because of two reasons:

* Badger keeps values separately from the LSM tree. This means that the
  compaction operations that clean up the LSM tree do not touch the values at
  all. Values need to be cleaned up separately.

* Concurrent read/write transactions could leave behind multiple values for a
  single key, because they're stored with different versions. These could
  accumulate, and take up unneeded space beyond the time these older versions
  are needed.

Badger relies on the client to perform garbage collection at a time of their
choosing. It provides the following method, which can be invoked at an
appropriate time:

* `DB.RunValueLogGC()`: This method is designed to do garbage collection while
  Badger is online. Along with randomly picking a file, it uses statistics
  generated by the LSM-tree compactions to pick files that are likely to lead to
  maximum space reclamation. It's recommended to be called during periods of low
  activity in your system, or periodically. One call would only result in
  removal of at max one log file. As an optimization, you could also immediately
  re-run it whenever it returns nil error (indicating a successful value log
  GC), as shown below.

  ```go
  ticker := time.NewTicker(5 * time.Minute)
  defer ticker.Stop()
  for range ticker.C {
  again:
    err := db.RunValueLogGC(0.7)
    if err == nil {
      goto again
    }
  }
  ```

* `DB.PurgeOlderVersions()`: This method is **DEPRECATED** since v1.5.0. Now,
  Badger's LSM tree automatically discards older/invalid versions of keys.

<Note>
  The `RunValueLogGC` method would not garbage collect the latest value log.
</Note>

## Database backup

There are two public API methods `DB.Backup()` and `DB.Load()` which can be used
to do online backups and restores. Badger v0.9 provides a CLI tool `badger`,
which can do offline backup/restore. Make sure you have `$GOPATH/bin` in your
PATH to use this tool.

The command below creates a version-agnostic backup of the database, to a file
`badger.bak` in the current working directory

```sh
badger backup --dir <path/to/badgerdb>
```

To restore `badger.bak` in the current working directory to a new database:

```sh
badger restore --dir <path/to/badgerdb>
```

See `badger --help` for more details.

If you have a Badger database that was created using v0.8 (or below), you can
use the `badger_backup` tool provided in v0.8.1, and then restore it using the
preceding command to upgrade your database to work with the latest version.

```sh
badger_backup --dir <path/to/badgerdb> --backup-file badger.bak
```

We recommend all users to use the `Backup` and `Restore` APIs and tools.
However, Badger is also rsync-friendly because all files are immutable, barring
the latest value log which is append-only. So, rsync can be used as rudimentary
way to perform a backup. In the following script, we repeat rsync to ensure that
the LSM tree remains consistent with the MANIFEST file while doing a full
backup.

```sh
#!/bin/bash
set -o history
set -o histexpand
# Makes a complete copy of a Badger database directory.
# Repeat rsync if the MANIFEST and SSTables are updated.
rsync -avz --delete db/ dst
while !! | grep -q "(MANIFEST\|\.sst)$"; do :; done
```

## Memory usage

Badger's memory usage can be managed by tweaking several options available in
the `Options` struct that's passed in when opening the database using `DB.Open`.

* Number of memtables (`Options.NumMemtables`)
  * If you modify `Options.NumMemtables`, also adjust
    `Options.NumLevelZeroTables` and `Options.NumLevelZeroTablesStall`
    accordingly.
* Number of concurrent compactions (`Options.NumCompactors`)
* Size of table (`Options.BaseTableSize`)
* Size of value log file (`Options.ValueLogFileSize`)

If you want to decrease the memory usage of Badger instance, tweak these options
(ideally one at a time) until you achieve the desired memory usage.


# Troubleshooting
Source: https://docs.hypermode.com/badger/troubleshooting

Common issues and solutions with Badger

## Writes are getting stuck

**Update: with the new `Value(func(v []byte))` API, this deadlock can no longer
happen.**

The following is true for users on Badger v1.x.

This can happen if a long running iteration with `Prefetch` is set to false, but
an `Item::Value` call is made internally in the loop. That causes Badger to
acquire read locks over the value log files to avoid value log GC removing the
file from underneath. As a side effect, this also blocks a new value log GC file
from being created, when the value log file boundary is hit.

Please see GitHub issues
[#293](https://github.com/hypermodeinc/badger/issues/293) and
[#315](https://github.com/hypermodeinc/badger/issues/315).

There are multiple workarounds during iteration:

1. Use `Item::ValueCopy` instead of `Item::Value` when retrieving value.
2. Set `Prefetch` to true. Badger would then copy over the value and release the
   file lock immediately.
3. When `Prefetch` is false, don't call `Item::Value` and do a pure key-only
   iteration. This might be useful if you just want to delete a lot of keys.
4. Do the writes in a separate transaction after the reads.

## Writes are really slow

Are you creating a new transaction for every single key update, and waiting for
it to `Commit` fully before creating a new one? This leads to very low
throughput.

We've created `WriteBatch` API which provides a way to batch up many updates
into a single transaction and `Commit` that transaction using callbacks to avoid
blocking. This amortizes the cost of a transaction really well, and provides the
most efficient way to do bulk writes.

```go
wb := db.NewWriteBatch()
defer wb.Cancel()

for i := 0; i < N; i++ {
  err := wb.Set(key(i), value(i), 0) // Will create txns as needed.
  handle(err)
}
handle(wb.Flush()) // Wait for all txns to finish.
```

Note that `WriteBatch` API doesn't allow any reads. For read-modify-write
workloads, you should be using the `Transaction` API.

## I don't see any disk writes

If you're using Badger with `SyncWrites=false`, then your writes might not be
written to value log and won't get synced to disk immediately. Writes to LSM
tree are done inmemory first, before they get compacted to disk. The compaction
would only happen once `BaseTableSize` has been reached. So, if you're doing a
few writes and then checking, you might not see anything on disk. Once you
`Close` the database, you'll see these writes on disk.

## Reverse iteration doesn't produce the right results

Just like forward iteration goes to the first key which is equal or greater than
the SEEK key, reverse iteration goes to the first key which is equal or lesser
than the SEEK key. Therefore, SEEK key would not be part of the results. You can
typically add a `0xff` byte as a suffix to the SEEK key to include it in the
results. See the following issues:
[#436](https://github.com/hypermodeinc/badger/issues/436) and
[#347](https://github.com/hypermodeinc/badger/issues/347).

## Which instances should I use for Badger?

We recommend using instances which provide local SSD storage, without any limit
on the maximum IOPS. In AWS, these are storage optimized instances like i3. They
provide local SSDs which clock 100K IOPS over 4KB blocks easily.

## I'm getting a closed channel error

```sh
panic: close of closed channel
panic: send on closed channel
```

If you're seeing panics like above, this would be because you're operating on a
closed DB. This can happen, if you call `Close()` before sending a write, or
multiple times. You should ensure that you only call `Close()` once, and all
your read/write operations finish before closing.

## Are there any Go specific settings that I should use?

We *highly* recommend setting a high number for `GOMAXPROCS`, which allows Go to
observe the full IOPS throughput provided by modern SSDs. In Dgraph, we have set
it to 128. For more details,
[see this thread](https://groups.google.com/d/topic/golang-nuts/jPb_h3TvlKE/discussion).

## Are there any Linux specific settings that I should use?

We recommend setting `max file descriptors` to a high number depending upon the
expected size of your data. On Linux and Mac, you can check the file descriptor
limit with `ulimit -n -H` for the hard limit and `ulimit -n -S` for the soft
limit. A soft limit of `65535` is a good lower bound. You can adjust the limit
as needed.

## I see "manifest has unsupported version: X (we support Y)" error

This error means you have a badger directory which was created by an older
version of badger and you're trying to open in a newer version of badger. The
underlying data format can change across badger versions and users have to
migrate their data directory. Badger data can be migrated from version X of
badger to version Y of badger by following the steps listed below. Assume you
were on badger v1.6.0 and you wish to migrate to v2.0.0 version.

1. Install badger version v1.6.0

   * `cd $GOPATH/src/github.com/dgraph-io/badger`
   * `git checkout v1.6.0`
   * `cd badger && go install`

     This should install the old badger binary in your `$GOBIN`.

2. Create Backup
   * `badger backup --dir path/to/badger/directory -f badger.backup`

3. Install badger version v2.0.0

   * `cd $GOPATH/src/github.com/dgraph-io/badger`
   * `git checkout v2.0.0`
   * `cd badger && go install`

     This should install the new badger binary in your `$GOBIN`.

4. Restore data from backup

   * `badger restore --dir path/to/new/badger/directory -f badger.backup`

     This creates a new directory on `path/to/new/badger/directory` and add
     badger data in newer format to it.

NOTE - The preceding steps shouldn't cause any data loss but please ensure the
new data is valid before deleting the old badger directory.

## Why do I need gcc to build badger? Does badger need Cgo?

Badger doesn't directly use Cgo but it relies on [https://github.com/DataDog/zstd](https://github.com/DataDog/zstd)
library for zstd compression and the library requires
[`gcc/cgo`](https://pkg.go.dev/cmd/cgo). You can build Badger without Cgo by
running `CGO_ENABLED=0 go build`. This builds Badger without the support for
ZSTD compression algorithm.

As of Badger versions
[v2.2007.4](https://github.com/hypermodeinc/badger/releases/tag/v2.2007.4) and
[v3.2103.1](https://github.com/hypermodeinc/badger/releases/tag/v3.2103.1) the
DataDog ZSTD library was replaced by pure Golang version and Cgo is no longer
required. The new library is
[backwards compatible in nearly all cases](https://discuss.dgraph.io/t/use-pure-go-zstd-implementation/8670/10):

<Note>
  Yes they're compatible both ways. The only exception is 0 bytes of input which
  gives 0 bytes output with the Go zstd. But you already have the
  zstd.WithZeroFrames(true) which will wrap 0 bytes in a header so it can be fed
  to DD zstd. This is only relevant when downgrading.
</Note>


# Community and Support
Source: https://docs.hypermode.com/community-and-support

Get help with Hypermode and connect with other developers

Whether you're just getting started or you're a seasoned developer, we're here
to help you every step of the way. We’re excited to have you as part of the
Hypermode community and look forward to seeing what you build!

## Community

[Discord](https://discord.hypermode.com) is our main forum where you can ask
questions, share your knowledge, and connect with other developers.

## Getting help

If you encounter a bug or have a feature request, you can open an issue on the
relevant GitHub repository:

* [Modus](https://github.com/hypermodeinc/modus/issues)
* [Hyp CLI](https://github.com/hypermodeinc/hyp-cli/issues)
* [Badger](https://github.com/hypermodeinc/badger/issues)

All paid Hypermode packages include commercial support. Customers can reach out
via the Hypermode Console or through email at
[help@hypermode.com](mailto:help@hypermode.com).

## Stay connected

Stay up-to-date with the latest news, updates, and announcements from Hypermode:

* **[X](https://x.com/hypermodeinc)**: follow us on X for the latest news and
  updates
* **[Blog](https://hypermode.com/blog)**: explore our blog for in-depth
  articles, tutorials, and case studies


# Configure Environment
Source: https://docs.hypermode.com/configure-environment

Define environment parameters for your app

On your first deployment, and when you add new connections thereafter, you may
need to configure your environment for your app to be ready for traffic.

## Connection secrets

If you included parameters for Connection Secrets in your
[app manifest](/modus/app-manifest), you'll need to add the parameter values in
the Hypermode Console.

From your project home, navigate to **Settings** → **Connections**. Add the
values for your defined connection authentication parameters.

## Model hosting

Where available, Hypermode defaults to shared model instances. Refer to the
[Hosted Models](/hosted-models) documentation for instructions on setting up
hosted models.

## Scaling your runtime resources

We're working to make runtime scaling self-service. In the meantime, reach out
at [help@hypermode.com](mailto:help@hypermode.com) for assistance with this
request.


# Create Project
Source: https://docs.hypermode.com/create-project

Initialize your Modus app with Hypermode

A Hypermode project represents your Modus app and associated models. You can
create a project through the Hypermode Console or Hyp CLI.

## Create with Hypermode Console

<Note>
  Hypermode relies on Git as a source for project deployment. Through the
  project creation flow, you'll connect Hypermode to your GitHub account.
</Note>

From your organization home, click **New Project**. Set a name for the project
and click **Create**.

Once you have created a project, Hypermode prompts you to finish setting up your
project using the CLI.

First, install the Modus CLI and initialize your app. For more information on
creating your first Modus app, visit the [Modus quickstart](modus/quickstart).

Next, initialize the app with Hypermode through the [Hyp CLI](/hyp-cli) and link
your GitHub repo with your Modus app to Hypermode using:

```bash
hyp link
```

This command adds a default GitHub Actions workflow to build your Modus app and
a Hypermode GitHub app for auto-deployment. Once initialized, each commit to the
target branch triggers a deployment.

You can also connect to an existing GitHub repository.

The last step is triggering your first deployment. If you linked your project
through the Hyp CLI, make sure to push your changes first to trigger a
deployment.


# Deploy Project
Source: https://docs.hypermode.com/deploy

A git-based flow for simple deployment

Hypermode features a native GitHub integration for the deployment of Hypermode
projects. The deployment includes your Modus app as well as any models defined
in the [app manifest](/modus/app-manifest).

<Note>
  Preview environments for live validation of pull requests are in development.
</Note>

## Link your project to GitHub

After you push your Modus app to GitHub, you can link your Hypermode project to
the repo through the Hyp CLI.

```bash
hyp link
```

## Build

When you link your project with Hypermode, the Hyp CLI adds a GitHub Actions
workflow to your repo that builds your Modus app to Hypermode on commit.

## Deploy

On successful build of your project, Hypermode automatically deploys your
project changes. For [hosted models](/hosted-models), Hypermode creates a
connection for your app to a shared or dedicated model instance.

You can view the deployment status from the Deployments tab within the Hypermode
Console.


# Hosted Models
Source: https://docs.hypermode.com/hosted-models

Iterate quickly with seamless access to the most popular models

Hypermode includes a set of shared models available for integration into your
app on a pay-per-token basis.

Need a bespoke model? You can include a model from
[Hugging Face](https://huggingface.co/) in your
[app manifest](/modus/app-manifest) and Hypermode runs and manages it for you.

## Setup

To use a Hypermode-hosted model, set `connection: "hypermode"`,
`provider: "hugging-face"`, and set `sourceModel` to be the model name as
specified on Hugging Face.

```json modus.json {3-7}
{
  ...
  "models": {
    "text-generator": {
      "sourceModel": "meta-llama/Llama-3.2-3B-Instruct",
      "provider": "hugging-face",
      "connection": "hypermode"
    }
  }
  ...
}
```

## Deployment mode

We run our most popular models as multi-tenant, shared instances across projects
and customers.

By default, if the model you use is available as a shared model, your app uses
these shared models at runtime. If the model you use isn't available as a shared
model, Hypermode automatically spins up a dedicated instance of the model for
your project.

## Shared models

These are the models available currently with shared instances:

* [`meta-llama/Llama-3.2-3B-Instruct`](https://huggingface.co/meta-llama/Llama-3.2-3B-Instruct)
* [`deepseek-ai/DeepSeek-R1-Distill-Llama-8B`](https://huggingface.co/deepseek-ai/DeepSeek-R1-Distill-Llama-8B)
* [`sentence-transformers/all-MiniLM-L6-v2`](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2)
* [`AntoineMC/distilbart-mnli-github-issues`](https://huggingface.co/AntoineMC/distilbart-mnli-github-issues)
* [`distilbert/distilbert-base-uncased-finetuned-sst-2-english`](https://huggingface.co/distilbert/distilbert-base-uncased-finetuned-sst-2-english)

<note>
  We're constantly evaluating model usage in determining new models to add to
  our shared catalog. Interested in consuming an open source model not listed
  here by the token? Let us know at
  [help@hypermode.com](mailto:help@hypermode.com).
</note>


# Hyp CLI
Source: https://docs.hypermode.com/hyp-cli

Comprehensive reference for the Hyp CLI commands and usage

Hyp CLI is a command-line tool for managing your Hypermode account and projects.
When using Hyp CLI alongside the Modus CLI, users get access to
[Hypermode-hosted models](/hosted-models).

## Install

Install Hyp CLI via npm.

```bash
npm install -g @hypermode/hyp-cli
```

## Commands

### `login`

Log in to your Hypermode account. When executed, this command redirects to the
Hypermode website to authenticate. It stores an authentication token locally and
prompts you to select your organization context.

### `logout`

Log out of your Hypermode account. This command clears your local authentication
token.

### `org switch`

Switch to a different org context within the CLI session.


# Integrate API
Source: https://docs.hypermode.com/integrate-api

Easily add intelligent features to your app

Hypermode makes it easy to incrementally add intelligence your app.

## API endpoint

You can find your project's API endpoint in the Hypermode Console, in your
project's Home tab, in the format `https://<slug>.hypermode.app/<path>`.

## API token

Hypermode protects your project's endpoint with an API key. In your project
dashboard, navigate to **Settings** → **API Keys** to find and manage your API
tokens.

From your app, you can call the API by passing the API token in the
`Authorization` header. Here's an example using the `fetch` API in JavaScript:

```javascript
const endpoint = "" // your API endpoint
const key = "" // your API key
// your graphql query
const query = `query {
  ...
}`

const response = await fetch(endpoint, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: key,
  },
  body: JSON.stringify({
    query: query,
  }),
})
const data = await response.json()
```

<Note>
  Additional authorization methods are under development. If your app requires a
  different protocol, reach out at
  [help@hypermode.com](mailto:help@hypermode.com).
</Note>


# Introduction
Source: https://docs.hypermode.com/introduction

Build Intelligent APIs.

{/* vale Google.Contractions = NO */}

## What is Hypermode?

{/* vale Google.Contractions = YES */}

Hypermode is a managed service that provides the workbench and infrastructure to
create **powerful, engaging, and secure AI assistants, APIs, and backend
services**.

With every push to Git, Hypermode automatically builds and deploys your
functions. It creates a live, scalable API for you to preview, test, and promote
to production.

## What's included with Hypermode?

Hypermode provides a suite of tools and services to help you build and manage
your intelligent APIs. Use one component or all of them together as the complete
backend for your app.

<CardGroup cols={2}>
  <Card title="Functions" icon="rectangle-code" href="/modus">
    Modus is an open source, serverless framework for building functions and
    APIs, powered by WebAssembly
  </Card>

  <Card title="Model Hosting" icon="cube" href="/hosted-models">
    Experiment rapidly with access to the most popular and newest models.
  </Card>

  <Card title="Graph Data Store" icon="chart-network" href="https://dgraph.io">
    Dgraph is a distributed, transactional graph database optimized for
    knowledge graph creation and management
  </Card>

  <Card title="Integrated Console" icon="display" href="/observe-functions">
    End-to-end observability and control for your functions, models, and data.
  </Card>
</CardGroup>

<img className="block" src="https://mintlify.s3.us-west-1.amazonaws.com/hypermode/images/console-screenshot.png" alt="Hypermode's console showing project, model, and API management." />


# Modify Organization
Source: https://docs.hypermode.com/modify-organization

Update organization attributes or delete your organization

Organizations contain a set of related projects and members. This forms the
billing envelope for Hypermode. You can modify your organization's name and slug
through the settings.

## Update organization name

Your organization name is a display name only and changing it doesn't impact
your running apps. To update your organization display name, click your
organization's name in the top navigation. Then, click **Settings** →
**General**. Enter a new name and click **Save**.

## Update organization slug

From your organization home view, click **Settings** → **General**. Enter a new
slug and click **Save**.

<Warning>
  When you update the organization slug, Hypermode reflects the new slug in your
  app endpoints across all projects. You must update any existing integrations
  that use the existing app endpoints. Make sure to communicate these changes
  with your team or stakeholders.
</Warning>

## Delete organization

If you no longer need an organization, you can permanently delete it. To delete
an organization, you must [delete all projects](/modify-project#delete-project)
first.

To delete an organization, click your organization's name in the top navigation.
Then, click **Settings** → **Delete**. Click **Delete** and enter the
organization's name as confirmation. This action is irreversible and permanently
deletes your organization.


# Modify Project
Source: https://docs.hypermode.com/modify-project

Update project attributes or delete your project

After you create a project, you can modify its name and slug through the project
settings.

## Update project name

Your project name is display-only and changing it doesn't impact your running
app. To update your project display name, click **Settings** → **General**.
Enter a new name and click **Save**.

## Update project slug

From your project view, click **Settings** → **General**. Enter a new slug and
click **Save**.

<Warning>
  If you update the project slug, you must update any existing integrations that
  use the existing app endpoints. Make sure to communicate these changes with
  your team or stakeholders.
</Warning>

## Delete project

If you no longer need a project, you can permanently delete it. Deleting a
project removes all associated endpoints, configurations, and data.

To delete a project, from the project in the console, click **Settings** →
**Delete**. Click **Delete** and enter the project’s name as confirmation. This
action is irreversible and permanently deletes all project data and
configuration.


# API Generation
Source: https://docs.hypermode.com/modus/api-generation

Create the signature for your API

Modus automatically creates an external API based on the endpoints defined in
your [app manifest](/modus/app-manifest#endpoints). Modus generates the API
signature based on the functions you export from your app.

## Exporting functions

Modus uses the default conventions for each language.

<Tabs>
  <Tab title="Go">
    Functions written in Go use starting capital letters to expose functions as public. Modus
    creates an external API for public functions from any file that belongs to the `main` package.

    The functions below generate an API endpoint with the signature

    ```graphql
    type Query {
      classifyText(text: String!, threshold: Float!): String!
    }
    ```

    Since the `classify` function isn't capitalized, Modus doesn't include it in the
    generated GraphQL API.

    ```go
    package main

    import (
      "errors"
      "fmt"
      "github.com/hypermodeAI/functions-go/pkg/models"
      "github.com/hypermodeAI/functions-go/pkg/models/experimental"
    )

    const modelName = "my-classifier"

    // this function takes input text and a probability threshold, and returns the
    // classification label determined by the model, if the confidence is above the
    // threshold; otherwise, it returns an empty string

    func ClassifyText(text string, threshold float32) (string, error) {
      predictions, err:= classify(text)
      if err != nil {
        return "", err
      }

      prediction := predictions[0]
      if prediction.Confidence < threshold {
        return "", nil
      }

      return prediction.Label, nil
    }

    func classify(texts ...string) ([]experimental.ClassifierResult, error) {
      model, err := models.GetModel[experimental.ClassificationModel](modelName)
      if err != nil {
        return nil, err
      }

      input, err := model.CreateInput(texts...)
      if err != nil {
        return nil, err
      }

      output, err := model.Invoke(input)
      if err != nil {
        return nil, err
      }

      if len(output.Predictions) != len(texts) {
        word := "prediction"
        if len(texts) > 1 {
          word += "s"
        }

        return nil, fmt.Errorf("expected %d %s, got %d", len(texts), word, len(output.Predictions))
      }

      return output.Predictions, nil
    }
    ```
  </Tab>

  <Tab title="AssemblyScript">
    Functions written in AssemblyScript use ES module-style `import` and `export` statements. With
    the default package configuration, Modus creates an external API for functions exported form the
    `index.ts` file located in the `functions/assembly` folder of your project.

    The functions below generate an API endpoint with the signature

    ```graphql
    type Query {
      classifyText(text: String!, threshold: Float!): String!
    }
    ```

    Since the `classify` function isn't exported from the module, Modus doesn't
    include it in the generated GraphQL API.

    ```ts
    import { models } from "@hypermode/modus-sdk-as"
    import {
      ClassificationModel,
      ClassifierResult,
    } from "@hypermode/modus-sdk-as/models/experimental/classification"

    const modelName: string = "my-classifier"

    // this function takes input text and a probability threshold, and returns the
    // classification label determined by the model, if the confidence is above the
    // threshold; otherwise, it returns an empty string
    export function classifyText(text: string, threshold: f32): string {
      const predictions = classify(text, threshold)

      const prediction = predictions[0]
      if (prediction.confidence < threshold) {
        return ""
      }

      return prediction.label
    }

    function classify(text: string, threshold: f32): ClassifierResult[] {
      const model = models.getModel<ClassificationModel>(modelName)
      const input = model.createInput([text])
      const output = model.invoke(input)

      return output.predictions
    }
    ```
  </Tab>
</Tabs>


# App Manifest
Source: https://docs.hypermode.com/modus/app-manifest

Define the resources for your app

The manifest for your Modus app allows you to configure the exposure and
resources for your functions at runtime. You define the manifest in the
`modus.json` file within the root of directory of your app.

## Structure

<CardGroup cols={2}>
  <Card title="Endpoints" icon="rectangle-code" href="#endpoints">
    Expose your functions for integration into your frontend or federated API
  </Card>

  <Card title="Connections" icon="router" href="#connections">
    Establish connectivity for external endpoints and model hosts
  </Card>

  <Card title="Models" icon="cube" href="#models">
    Define inference services for use in your functions
  </Card>

  <Card title="Collections" icon="table" href="#collections">
    Define sets of text data to enable natural language search
  </Card>
</CardGroup>

### Base manifest

A simple manifest, which exposes a single GraphQL endpoint with a bearer token
for authentication, looks like this:

```json modus.json
{
  "$schema": "https://schema.hypermode.com/modus.json",
  "endpoints": {
    "default": {
      "type": "graphql",
      "path": "/graphql",
      "auth": "bearer-token"
    }
  }
}
```

## Endpoints

Endpoints make your functions available outside of your Modus app. The
`endpoints` object in the app manifest allows you to define these endpoints for
integration into your frontend or federated API.

Each endpoint requires a unique name, specified as a key containing only
alphanumeric characters and hyphens.

<Note>
  Only a GraphQL endpoint is available currently, but the modular design of
  Modus allows for the introduction of additional endpoint types in the future.
</Note>

### GraphQL endpoint

This endpoint type supports the GraphQL protocol to communicate with external
clients. You can use a GraphQL client, such as
[urql](https://github.com/urql-graphql/urql) or
[Apollo Client](https://github.com/apollographql/apollo-client), to interact
with the endpoint.

**Example:**

```json modus.json
{
  "endpoints": {
    "default": {
      "type": "graphql",
      "path": "/graphql",
      "auth": "bearer-token"
    }
  }
}
```

<ResponseField name="type" type="string" required>
  Always set to `"graphql"` for this endpoint type.
</ResponseField>

<ResponseField name="path" type="string" required>
  The path for the endpoint. Must start with a forward slash `/`.
</ResponseField>

<ResponseField name="auth" type="string" required>
  The authentication method for the endpoint. Options are `"bearer-token"` or
  `"none"`. See [Authentication](/modus/authentication) for additional details.
</ResponseField>

## Connections

Connections establish connectivity and access to external services. They're used
for HTTP and GraphQL APIs, database connections, and externally hosted AI
models. The `connections` object in the app manifest allows you to define these
hosts, for secure access from within a function.

Each connection requires a unique name, specified as a key containing only
alphanumeric characters and hyphens.

Each connection has a `type` property, which controls how it's used and which
additional properties are available. The following table lists the available
connection types:

| Type         | Purpose                          | Function Classes            |
| :----------- | :------------------------------- | :-------------------------- |
| `http`       | Connect to an HTTP(S) web server | `http`, `graphql`, `models` |
| `dgraph`     | Connect to a Dgraph database     | `dgraph`                    |
| `mysql`      | Connect to a MySQL database      | `mysql`                     |
| `neo4j`      | Connect to a Neo4j database      | `neo4j`                     |
| `postgresql` | Connect to a PostgreSQL database | `postgresql`                |

<Warning>
  **Don't include secrets directly in the manifest!**

  If your connection requires authentication, you can include *placeholders* in
  connection properties which resolve to their respective secrets at runtime.

  When developing locally,
  [set secrets using environment variables](/modus/run-locally#environment-secrets).

  When deployed on Hypermode, set the actual secrets via the Hypermode Console,
  where they're securely stored until needed.
</Warning>

### HTTP connection

This connection type supports the HTTP and HTTPS protocols to communicate with
external hosts. You can use the [HTTP APIs](/modus/sdk/assemblyscript/http) in
the Modus SDK to interact with the host.

This connection type is also used for
[GraphQL APIs](/modus/sdk/assemblyscript/graphql) and to invoke externally
hosted AI [models](/modus/sdk/assemblyscript/models).

**Example:**

```json modus.json
{
  "connections": {
    "openai": {
      "type": "http",
      "baseUrl": "https://api.openai.com/",
      "headers": {
        "Authorization": "Bearer {{API_KEY}}"
      }
    }
  }
}
```

<ResponseField name="type" type="string" required>
  Always set to `"http"` for this connection type.
</ResponseField>

<ResponseField name="baseUrl" type="string" required>
  Base URL for connections to the host. Must end with a trailing slash and may
  contain path segments if necessary.

  Example: `"https://api.example.com/v1/"`
</ResponseField>

<ResponseField name="endpoint" type="string" required>
  Full URL endpoint for connections to the host.

  Example: `"https://models.example.com/v1/classifier"`
</ResponseField>

<Note>
  You must include either a `baseUrl` or an `endpoint`, but not both.

  * Use `baseUrl` for connections to a host with a common base URL.
  * Use `endpoint` for connections to a specific URL.

  Typically, you'll use the `baseUrl` field. However, some APIs, such as
  `graphql.execute`, require the full URL in the `endpoint` field.
</Note>

<ResponseField name="headers" type="object">
  If provided, requests on the connection include these headers. Each key-value pair is a header name and value.

  Values may include variables using the `{{VARIABLE}}` template syntax, which
  resolve at runtime to secrets provided for each connection, via the Hypermode
  Console.

  <Accordion title="Examples">
    This example specifies a header named `Authorization` that uses the `Bearer`
    scheme. A secret named `AUTH_TOKEN` provides the token:

    ```json
    "headers": {
      "Authorization": "Bearer {{AUTH_TOKEN}}"
    }
    ```

    This example specifies a header named `X-API-Key` provided by a secret named
    `API_KEY`:

    ```json
    "headers": {
      "X-API-Key": "{{API_KEY}}"
    }
    ```

    You can use a special syntax for connections that require
    [HTTP basic authentication](https://en.wikipedia.org/wiki/Basic_access_authentication).
    In this example, secrets named `USERNAME` and `PASSWORD` combined and then are
    base64-encoded to form a compliant `Authorization` header value:

    ```json
    "headers": {
      "Authorization": "Basic {{base64(USERNAME:PASSWORD)}}"
    }
    ```
  </Accordion>
</ResponseField>

<ResponseField name="queryParameters" type="object">
  If provided, requests on the connection include these query parameters, appended
  to the URL. Each key-value pair is a parameter name and value.

  Values may include variables using the `{{VARIABLE}}` template syntax, which
  resolve at runtime to secrets provided for each connection, via the Hypermode
  Console.

  <Accordion title="Example">
    This example specifies a query parameter named `key` provided by a secret named
    `API_KEY`:

    ```json
    "queryParameters": {
      "key": "{{API_KEY}}"
    }
    ```
  </Accordion>
</ResponseField>

### Dgraph connection

This connection type supports connecting to Dgraph databases. You can use the
[Dgraph APIs](/modus/sdk/assemblyscript/dgraph) in the Modus SDK to interact
with the database.

**Example:**

```json modus.json
{
  "connections": {
    "my-dgraph": {
      "type": "dgraph",
      "grpcTarget": "frozen-mango.grpc.eu-central-1.aws.cloud.dgraph.io:443",
      "key": "{{DGRAPH_API_KEY}}"
    }
  }
}
```

<ResponseField name="type" type="string" required>
  Always set to `"dgraph"` for this connection type.
</ResponseField>

<ResponseField name="grpcTarget" type="string" required>
  The gRPC target for the Dgraph database.
</ResponseField>

<ResponseField name="key" type="string" required>
  The API key for the Dgraph database.
</ResponseField>

### MySQL connection

This connection type supports connecting to MySQL databases. You can use the
[MySQL APIs](/modus/sdk/assemblyscript/mysql) in the Modus SDK to interact with
the database.

**Example:**

```json modus.json
{
  "connections": {
    "my-database": {
      "type": "mysql",
      "connString": "mysql://{{USERNAME}}:{{PASSWORD}}@db.example.com:3306/dbname?tls=true"
    }
  }
}
```

<ResponseField name="type" type="string" required>
  Always set to `"mysql"` for this connection type.
</ResponseField>

<ResponseField name="connString" type="string" required>
  The connection string for the MySQL database.

  Values may include variables using the `{{VARIABLE}}` template syntax, which
  resolve at runtime to secrets provided for each connection, via the Hypermode
  Console.

  The connection string in the preceding example includes:

  * A username and password provided by secrets named `USERNAME` & `PASSWORD`
  * A host named `db.example.com` on port `3306`
  * A database named `dbname`
  * Encryption enabled via `tls=true` - which is highly recommended for secure
    connections

  Set the connection string using a URI format
  [as described in the MySQL documentation](https://dev.mysql.com/doc/refman/8.4/en/connecting-using-uri-or-key-value-pairs.html#connecting-using-uri).

  However, any optional parameters provided should be in the form specified by the
  Go MySQL driver used by the Modus Runtime,
  [as described here](https://github.com/go-sql-driver/mysql/blob/master/README.md#parameters)

  For example, use `tls=true` to enable encryption (not `sslmode=require`).
</ResponseField>

### Neo4j connection

This connection type supports connecting to Neo4j databases. You can use the
[Neo4j APIs](/modus/sdk/assemblyscript/neo4j) in the Modus SDK to interact with
the database.

**Example:**

```json modus.json
{
  "connections": {
    "my-neo4j": {
      "type": "neo4j",
      "dbUri": "bolt://localhost:7687",
      "username": "neo4j",
      "password": "{{NEO4J_PASSWORD}}"
    }
  }
}
```

<ResponseField name="type" type="string" required>
  Always set to `"neo4j"` for this connection type.
</ResponseField>

<ResponseField name="dbUri" type="string" required>
  The URI for the Neo4j database.
</ResponseField>

<ResponseField name="username" type="string" required>
  The username for the Neo4j database.
</ResponseField>

<ResponseField name="password" type="string" required>
  The password for the Neo4j database.
</ResponseField>

### PostgreSQL connection

This connection type supports connecting to PostgreSQL databases. You can use
the [PostgreSQL APIs](/modus/sdk/assemblyscript/postgresql) in the Modus SDK to
interact with the database.

**Example:**

```json modus.json
{
  "connections": {
    "my-database": {
      "type": "postgresql",
      "connString": "postgresql://{{PG_USER}}:{{PG_PASSWORD}}@db.example.com:5432/data?sslmode=require"
    }
  }
}
```

<ResponseField name="type" type="string" required>
  Always set to `"postgresql"` for this connection type.
</ResponseField>

<ResponseField name="connString" type="string" required>
  The connection string for the PostgreSQL database.

  Values may include variables using the `{{VARIABLE}}` template syntax, which
  resolve at runtime to secrets provided for each connection, via the Hypermode
  Console.

  The connection string in the preceding example includes:

  * A username and password provided by secrets named `PG_USER` & `PG_PASSWORD`
  * A host named `db.example.com` on port `5432`
  * A database named `data`
  * SSL mode set to `require` - which is highly recommended for secure connections

  Refer to
  [the PostgreSQL documentation](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING)
  for more details on connection strings.

  <Tip>
    Managed PostgreSQL providers often provide a pre-made connection string for you
    to copy. Check your provider's documentation for details.

    For example, if using Neon, refer to the
    [Neon documentation](https://neon.tech/docs/connect/connect-from-any-app).
  </Tip>
</ResponseField>

<Tip>
  See [Running locally with secrets](/modus/run-locally#environment-secrets) for
  more details on how to set secrets for local development.
</Tip>

## Models

AI models are a core resource for inferencing. The `models` object in the app
manifest allows you to easily define models, whether hosted by Hypermode or
another host.

Each model requires a unique name, specified as a key, containing only
alphanumeric characters and hyphens.

```json modus.json
{
  "models": {
    "text-generator": {
      "sourceModel": "meta-llama/Llama-3.2-3B-Instruct",
      "provider": "hugging-face",
      "connection": "hypermode"
    }
  }
}
```

<ResponseField name="sourceModel" type="string" required>
  Original relative path of the model within the provider's repository.
</ResponseField>

<ResponseField name="provider" type="string">
  Source provider of the model. If the `connection` value is `hypermode`, this
  field is mandatory. `hugging-face` is currently the only supported option.
</ResponseField>

<ResponseField name="connection" type="string" required>
  Connection for the model instance.

  * Specify `"hypermode"` for models that [Hypermode hosts](/hosted-models).
  * Otherwise, specify a name that matches a connection defined in the
    [`connections`](#connections) section of the manifest.
</ResponseField>

<Tip>
  When using `hugging-face` as the `provider` and `hypermode` as the `connection`,
  Hypermode automatically facilitates the connection to an instance of a shared or
  dedicated instance of the model. Your project's functions securely access the
  hosted model, with no further configuration required. For more details, see
  [hosted models](/hosted-models).
</Tip>

## Collections

Collections simplify the usage of vector embeddings to build natural language
search features. The `collections` object allows you to define indexed data
types that are automatically embedded and searchable based on the search method
you define.

Each collection requires a unique name, specified as a key, containing only
alphanumeric characters and hyphens.

For more detail on implementing Collections, see [Search](/modus/search).

```json modus.json
{
  "collections": {
    "myProducts": {
      "searchMethods": {
        "searchMethod": {
          "embedder": "myEmbedder",
          "index": {
            "type": "sequential"
          }
        }
      }
    }
  }
}
```

<ResponseField name="searchMethods" type="object" required>
  Search methods define a pair of an embedder and index to make available for
  searching the data in your collection.
</ResponseField>

<ResponseField name="embedder" type="string" required>
  The function name to embed text added to the collection.
</ResponseField>

<ResponseField name="index" type="string">
  If provided, describes the index mechanism used by the search method. `type`:
  specifies the type of the index. For example, `sequential` (default).
</ResponseField>


# Authentication
Source: https://docs.hypermode.com/modus/authentication

Protect your API

It's easy to secure your Modus app with authentication. Modus currently supports
bearer token authentication, with additional authentication methods coming soon.

## Bearer tokens

Modus supports authentication via the `Authorization` header in HTTP requests.
You can use the `Authorization` header to pass a bearer JSON Web Token (JWT) to
your Modus app. The token authenticates the user and authorize access to
resources.

To use bearer token authentication for your Modus app, be sure to set the `auth`
property on your endpoint to `"bearer-token"` in your
[app manifest](/modus/app-manifest#endpoints).

### Setting verification keys

Once set, Modus verifies tokens passed in the `Authorization` header of incoming
requests against the public keys you provide. To enable this verification, you
must pass the public keys using the `MODUS_PEMS` or `MODUS_JWKS_ENDPOINTS`
environment variable.

The value of the `MODUS_PEMS` or `MODUS_JWKS_ENDPOINTS` environment variable
should be a JSON object with the public keys as key-value pairs. This is an
example of how to set the `MODUS_PEMS` and `MODUS_JWKS_ENDPOINTS` environment
variable:

<CodeGroup>
  ```bash MODUS_PEMS
  export MODUS_PEMS='{\"key1\":\"-----BEGIN PUBLIC KEY-----\\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwJ9z1z1z1z1z1z\\n-----END PUBLIC KEY-----\"}'
  ```

  ```bash MODUS_JWKS_ENDPOINTS
  export MODUS_JWKS_ENDPOINTS='{"my-auth-provider":"https://myauthprovider.com/application/o/myappname/.wellknown/jwks.json"}'
  ```
</CodeGroup>

<Tip>
  When deploying your Modus app on Hypermode, the bearer token authentication is
  automatically set up.
</Tip>

### Verifying tokens

To verify the token, Modus uses the public keys passed via the `MODUS_PEMS`
environment variable. If the token is verifiable with any of the verification
keys provided, Modus decodes the JWT token and passes the decoded claims as an
environment variable.

### Accessing claims

The decoded claims are available through the `auth` API in the Modus SDK.

To access the decoded claims, use the `getJWTClaims()` function. The function
allows the user to pass in a class to deserialize the claims into, and returns
an instance of the class with the claims.

This allows users to access the claims in the token and use them to authenticate
and authorize users in their Modus app.

<CodeGroup>
  ```go Go
  import github.com/hypermodeinc/modus/sdk/go/pkg/auth

  type ExampleClaims struct {
      Sub string `json:"sub"`
      Exp int64  `json:"exp"`
      Iat int64  `json:"iat"`
  }

  func GetClaims() (*ExampleClaims, error) {
      return auth.GetJWTClaims[*ExampleClaims]()
  }
  ```

  ```ts AssemblyScript
  import { auth } from "@hypermode/modus-sdk-as"

  @json
  export class ExampleClaims {
    public sub!: string
    public exp!: i64
    public iat!: i64
  }

  export function getClaims(): ExampleClaims {
    return auth.getJWTClaims<ExampleClaims>()
  }
  ```
</CodeGroup>


# Changelog
Source: https://docs.hypermode.com/modus/changelog

The latest changes and improvements in Modus

Welcome to the Modus changelog! Here you'll find the latest improvements to the
Modus framework. Stay informed about what's new and what's changed to make the
most out of Modus.

Here's a short summary of the larger items shipped with each major or minor
release. For a more detailed list of changes, please refer to
[the full change log in GitHub](https://github.com/hypermodeinc/modus/blob/main/CHANGELOG.md).

## Version history

| Version | Date       | Description                                                  |
| ------- | ---------- | ------------------------------------------------------------ |
| 0.17.x  | 2025-01-24 | MySQL support, local model tracing, and OpenAI improvements. |
| 0.16.x  | 2024-12-23 | Local time and time zone support                             |
| 0.15.x  | 2024-12-13 | Neo4j support                                                |
| 0.14.x  | 2024-11-23 | Modus API Explorer + in-code documentation                   |
| 0.13.x  | 2024-10-17 | First release of Modus as an open source framework 🎉        |

Stay tuned for more updates and improvements as we continue to enhance Modus!


# Data Fetching
Source: https://docs.hypermode.com/modus/data-fetching

Pull data into your app

Modus makes it simple to fetch data from external sources. The specific data
source you're retrieving from determines the method you use to interact with it.

## Fetching from databases

### PostgreSQL

PostgreSQL is a powerful, open source relational database system. Modus provides
a simple way to interact with PostgreSQL databases with the `postgresql` APIs.

Here is an example of fetching a person from a PostgreSQL database using the
Modus SDK:

<CodeGroup>
  ```go Go
  package main

  import (
    "github.com/hypermodeinc/modus/sdk/go/pkg/postgresql"
  )

  // the name of the PostgreSQL connection, as specified in the modus.json manifest
  const connection = "my-database"

  type Person struct {
    Name string `json:"name"`
    Age  int    `json:"age"`
  }

  func GetPerson(name string) (*Person, error) {
    const query = "select * from persons where name = $1"
    rows, _, _ := postgresql.Query[Person](connection, query, name)
    return &rows[0], nil
  }
  ```

  ```ts AssemblyScript
  import { postgresql } from "@hypermode/modus-sdk-as"

  // the name of the PostgreSQL connection, as specified in the modus.json manifest
  const connection = "my-database"

  @json
  class Person {
    name!: string
    age!: i32
  }

  export function getPerson(name: string): Person {
    const query = "select * from persons where name = $1"

    const params = new postgresql.Params()
    params.push(name)

    const response = postgresql.query<Person>(connection, query, params)
    return response.rows[0]
  }
  ```
</CodeGroup>

### Dgraph

Dgraph is a distributed, transactional graph database. Modus offers an easy way
to query and mutate data in Dgraph with the `dgraph` APIs.

Here is an example of fetching a person from a Dgraph database using the Modus
SDK:

<CodeGroup>
  ```go Go
  package main

  import (
    "encoding/json"
    "github.com/hypermodeinc/modus/sdk/go/pkg/dgraph"
  )

  // the name of the Dgraph connection, as specified in the modus.json manifest
  const connection = "my-dgraph"

  // declare structures used to parse the JSON document returned by Dgraph query.
  type Person struct {
    Name string `json:"name,omitempty"`
    Age  int32  `json:"age,omitempty"`
  }

  // Dgraph returns an array of Persons
  type GetPersonResponse struct {
    Persons []*Person `json:"persons"`
  }

  func GetPerson(name string) (*Person, error) {
    statement := `query getPerson($name: string!) {
      persons(func: eq(name, $name))  {
        name
        age
      }
    }
    `
    variables := map[string]string{
      "$name": name,
    }

    response, _ := dgraph.Execute(connection, &dgraph.Request{
      Query: &dgraph.Query{
        Query:     statement,
        Variables: variables,
      },
    })

    var data GetPersonResponse
    json.Unmarshal([]byte(response.Json), &data)

    return data.Persons[0], nil
  }

  ```

  ```ts AssemblyScript
  import { dgraph } from "@hypermode/modus-sdk-as"
  import { JSON } from "json-as"

  // the name of the Dgraph connection, as specified in the modus.json manifest
  const connection: string = "my-dgraph"

  // declare classes used to parse the JSON document returned by Dgraph query.
  @json
  class Person {
    name: string = ""
    age: i32 = 0
  }

  // Dgraph returns an array of objects
  @json
  class GetPersonResponse {
    persons: Person[] = []
  }

  export function getPerson(name: string): Person {
    const statement = `  
    query getPerson($name: string) {
      persons(func: eq(name, $name))  {
          name
          age
      }
    }`

    const vars = new dgraph.Variables()
    vars.set("$name", name)

    const resp = dgraph.execute(
      connection,
      new dgraph.Request(new dgraph.Query(statement, vars)),
    )
    const persons = JSON.parse<GetPersonResponse>(resp.Json).persons
    return persons[0]
  }
  ```
</CodeGroup>

### Neo4j

Neo4j is a graph database management system. Modus provides a simple way to
query and mutate data in Neo4j with the `neo4j` APIs.

Here is an example of mutating & fetching a person from a Neo4j database using
the Modus SDK:

<CodeGroup>
  ```go Go
  package main

  import (
    "github.com/hypermodeinc/modus/sdk/go/pkg/neo4j"
  )


  const host = "my-database"

  func CreatePeopleAndRelationships() (string, error) {
    people := []map[string]any{
      {"name": "Alice", "age": 42, "friends": []string{"Bob", "Peter", "Anna"}},
      {"name": "Bob", "age": 19},
      {"name": "Peter", "age": 50},
      {"name": "Anna", "age": 30},
    }

    for _, person := range people {
      _, err := neo4j.ExecuteQuery(host,
        "MERGE (p:Person {name: $person.name, age: $person.age})",
        map[string]any{"person": person})
      if err != nil {
        return "", err
      }
    }

    for _, person := range people {
      if person["friends"] != "" {
        _, err := neo4j.ExecuteQuery(host, `
          MATCH (p:Person {name: $person.name})
                  UNWIND $person.friends AS friend_name
                  MATCH (friend:Person {name: friend_name})
                  MERGE (p)-[:KNOWS]->(friend)
        `, map[string]any{
          "person": person,
        })
        if err != nil {
          return "", err
        }
      }
    }

    return "People and relationships created successfully", nil
  }

  type Person struct {
    Name string `json:"name"`
    Age  int64  `json:"age"`
  }

  func GetAliceFriendsUnder40() ([]Person, error) {
    response, err := neo4j.ExecuteQuery(host, `
          MATCH (p:Person {name: $name})-[:KNOWS]-(friend:Person)
          WHERE friend.age < $age
          RETURN friend
          `,
      map[string]any{
        "name": "Alice",
        "age":  40,
      },
      neo4j.WithDbName("neo4j"),
    )
    if err != nil {
      return nil, err
    }

    nodeRecords := make([]Person, len(response.Records))

    for i, record := range response.Records {
      node, _ := neo4j.GetRecordValue[neo4j.Node](record, "friend")
      name, err := neo4j.GetProperty[string](&node, "name")
      if err != nil {
        return nil, err
      }
      age, err := neo4j.GetProperty[int64](&node, "age")
      if err != nil {
        return nil, err
      }
      nodeRecords[i] = Person{
        Name: name,
        Age:  age,
      }
    }

    return nodeRecords, nil
  }
  ```

  ```ts AssemblyScript
  import { neo4j } from "@hypermode/modus-sdk-as"

  // This host name should match one defined in the modus.json manifest file.
  const hostName: string = "my-database"

  @json
  class Person {
    name: string
    age: i32
    friends: string[] | null

    constructor(name: string, age: i32, friends: string[] | null = null) {
      this.name = name
      this.age = age
      this.friends = friends
    }
  }

  export function CreatePeopleAndRelationships(): string {
    const people: Person[] = [
      new Person("Alice", 42, ["Bob", "Peter", "Anna"]),
      new Person("Bob", 19),
      new Person("Peter", 50),
      new Person("Anna", 30),
    ]

    for (let i = 0; i < people.length; i++) {
      const createPersonQuery = `
        MATCH (p:Person {name: $person.name})
        UNWIND $person.friends AS friend_name
        MATCH (friend:Person {name: friend_name})
        MERGE (p)-[:KNOWS]->(friend)
      `
      const peopleVars = new neo4j.Variables()
      peopleVars.set("person", people[i])
      const result = neo4j.executeQuery(hostName, createPersonQuery, peopleVars)
      if (!result) {
        throw new Error("Error creating person.")
      }
    }

    return "People and relationships created successfully"
  }

  export function GetAliceFriendsUnder40(): Person[] {
    const vars = new neo4j.Variables()
    vars.set("name", "Alice")
    vars.set("age", 40)

    const query = `
      MATCH (p:Person {name: $name})-[:KNOWS]-(friend:Person)
          WHERE friend.age < $age
          RETURN friend
    `

    const result = neo4j.executeQuery(hostName, query, vars)
    if (!result) {
      throw new Error("Error getting friends.")
    }

    const personNodes: Person[] = []

    for (let i = 0; i < result.Records.length; i++) {
      const record = result.Records[i]
      const node = record.getValue<neo4j.Node>("friend")
      const person = new Person(
        node.getProperty<string>("name"),
        node.getProperty<i32>("age"),
      )
      personNodes.push(person)
    }

    return personNodes
  }
  ```
</CodeGroup>

## Fetching from APIs

### HTTP

HTTP protocols underpin RESTful APIs with OpenAPI schemas. Modus provides a
convenient way to interact with any external HTTP API using the `http` APIs in
the Modus SDK.

Here is an example of fetching a person from an HTTP API using the Modus SDK:

<CodeGroup>
  ```go Go
  package main

  import (
    "encoding/json"
    "fmt"
    "github.com/hypermodeinc/modus/sdk/go/pkg/http"
  )

  // declare structures used to parse the JSON document returned by the REST API
  type Person struct {
    Name string    `json:"name,omitempty"`
    Age  int32     `json:"age,omitempty"`
  }

  func GetPerson(name string) (*Person, error) {
    url := fmt.Sprintf("https://example.com/api/person?name=%s", name)
    response, _ := http.Fetch(url)

    // The API returns Person object as JSON
    var person Person
    response.JSON(&person)

    return person, nil
  }

  ```

  ```ts AssemblyScript
  import { http } from "@hypermode/modus-sdk-as"

  @json
  class Person {
    name: string = ""
    age: i32 = 0
  }

  export function getPerson(name: string): Person {
    const url = `https://example.com/api/people?name=${name}`

    const response = http.fetch(url)

    // the API returns Person object as JSON
    return response.json<Person>()
  }
  ```
</CodeGroup>

### GraphQL

GraphQL is a data-centric query language for APIs that allows you to fetch only
the data you need. With the `graphql` APIs in the Modus SDK, you can easily
fetch data from any GraphQL endpoint.

Here is an example of fetching a person from a GraphQL API using the Modus SDK:

<CodeGroup>
  ```go Go
  import (
    "encoding/json"
    "github.com/hypermodeinc/modus/sdk/go/pkg/graphql"
  )

  // the name of the GraphQL connection, as specified in the modus.json manifest
  const connection = "my-graphql-api"

  // declare structures used to parse the JSON document returned
  type Person struct {
    Name string    `json:"name,omitempty"`
    Age  int32     `json:"age,omitempty"`
  }

  type GetPersonResponse struct {
    Person *Person `json:"getPerson"`
  }

  func GetPerson(name string) (*Person, error) {
    statement := `query getPerson($name: String!) {
        getPerson(name: $name) {
          age
          name
        }
      }`

    vars := map[string]any{
       "name": name,
    }

    response, _ := graphql.Execute[GetPersonResponse](connection, statement, vars)

    return response.Data.Person, nil
  }
  ```

  ```ts AssemblyScript
  import { graphql } from "@hypermode/modus-sdk-as"

  // the name of the GraphQL connection, as specified in the modus.json manifest
  const connection: string = "my-graphql-api"

  // declare classes used to parse the JSON document returned
  @json
  class Person {
    name: string = ""
    age: i32 = 0
  }
  @json
  class GetPersonResponse {
    getPerson: Person | null
  }

  export function getPerson(name: string): Person | null {
    const statement = `
      query getPerson($name: String!) {
        getPerson(name: $name) {
          age
          name
        }
      }`

    const vars = new graphql.Variables()
    vars.set("name", name)

    const response = graphql.execute<GetPersonResponse>(
      connection,
      statement,
      vars,
    )

    return response.data!.getPerson
  }
  ```
</CodeGroup>


# Using DeepSeek
Source: https://docs.hypermode.com/modus/deepseek-model

Use the DeepSeek-R1 Model with your Modus app

`DeepSeek-R1` is an open source AI reasoning model that rivals the performance
of frontier models such as OpenAI's o1 in complex reasoning tasks like math and
coding. Benefits of DeepSeek include:

* **Performance**: `DeepSeek-R1` achieves comparable results to OpenAI's o1
  model on several benchmarks.
* **Efficiency**: The model uses significantly fewer parameters and therefore
  operates at a lower cost relative to competing frontier models.
* **Open Source**: The open source license allows both commercial and
  non-commercial usage of the model weights and associated code.
* **Novel training approach**: The research team developed DeepSeek-R1 through a
  multi-stage approach that combines reinforcement learning, fine-tuning, and
  data distillation.
* **Distilled versions**: The DeepSeek team released smaller, distilled models
  based on DeepSeek-R1 that offer high reasoning capabilities with fewer
  parameters.

In this guide we review how to use the `DeepSeek-R1` model in your Modus app.

## Options for using DeepSeek with Modus

There are two options for using `DeepSeek-R1` in your Modus app:

1. [Use the distilled `DeepSeek-R1` model hosted by Hypermode](#using-the-distilled-deepseek-model-hosted-by-hypermode)
   Hypermode hosts and makes available the distilled DeepSeek model based on
   `Llama-3.1-8B` enabling Modus apps to use it in both local development
   environments and deployed applications.

2. [Use the DeepSeek Platform API with your Modus app](#using-the-deepseek-platform-api-with-modus)
   Access DeepSeek models hosted on the DeepSeek platform by configuring a
   DeepSeek connection in your Modus app and using your DeepSeek API key

## Using the distilled DeepSeek model hosted by Hypermode

The open source `DeepSeek-R1-Distill-Llama-8B` DeepSeek model is available on
Hypermode as a [shared model](/hosted-models#shared-models). This means that we
can invoke this model in a Modus app in both a local development environment and
also in an app deployed on Hypermode.

The `DeepSeek-R1-Distill-Llama-8B` model is a distilled version of the
DeepSeek-R1 model which has been fine-tuned using the `Llama-3.1-8B` model as a
base model, using samples generated by DeepSeek-R1.

Distilled models offer similar high reasoning capabilities with fewer
parameters.

<iframe
  src="https://www.youtube.com/embed/ICRwZ8ywR9Q"
  title="DeepSeek + Modus"
  frameborder="0"
  allow="accelerometer; autoplay; clipboard-write;
encrypted-media; gyroscope; picture-in-picture"
  allowfullscreen
  style={{ aspectRatio: "16 / 9", width: "100%" }}
/>

<Steps>
  <Step title="Create a Modus app">
    If you haven't already, create a new modus app. Skip this step if you already
    have a Modus app.

    ```sh
    modus new
    ```

    <Tip>
      See [the Modus Quickstart](quickstart) for more information about creating
      Modus projects.
    </Tip>
  </Step>

  <Step title="Add the DeepSeek model to your app manifest">
    Update your Modus app manifest `modus.json` file to specify the
    `DeepSeek-R1-Distill-Llama-8B` model hosted on Hypermode.

    ```json modus.json
      "models": {
        "deepseek-reasoner": {
          "sourceModel": "deepseek-ai/DeepSeek-R1-Distill-Llama-8B",
          "provider": "hugging-face",
          "connection": "hypermode"
        }
      },
    ```

    <Note>
      Note that we named the model `deepseek-reasoner` in our app manifest, which we
      use to access the model in our Modus function.
    </Note>
  </Step>

  <Step title="Use the Hyp CLI to sign in to Hypermode">
    To use Hypermode hosted models in our local development environment we use the
    `hyp` CLI to log in to Hypermode.

    Install the `hyp` CLI if not previously installed.

    ```sh
    npm i -g @hypermode/hyp-cli
    ```

    Log into Hypermode using the command:

    ```sh
    hyp login
    ```

    If signing in for the first time, Hypermode prompts to create an account and
    specify an organization.
  </Step>

  <Step title="Write a function to invoke the model">
    You can now invoke the model in your Modus app's functions using the Modus
    models interface.

    Here we write a function that takes a prompt as input, invokes the DeepSeek
    model, and returns the generated text as output. At runtime this function
    becomes a GraphQL Query field in the GraphQL API generated by Modus.

    <CodeGroup>
      ```go Go
      package main

      import (
         "strings"

         "github.com/hypermodeinc/modus/sdk/go/pkg/models"
         "github.com/hypermodeinc/modus/sdk/go/pkg/models/openai"
      )

      func GenerateText(prompt string) (string, error) {

         model, err := models.GetModel[openai.ChatModel]("deepseek-reasoner")
         if err != nil {
             return "", err
         }

         // DeepSeek recommends not using a system prompt and including all instructions in the user prompt
         input, err := model.CreateInput(
             openai.NewUserMessage(prompt),
         )
         if err != nil {
             return "", err
         }

         // DeepSeek recommends setting temperature within the range of 0.5-0.7 with 0.6 the recommended default
         input.Temperature = 0.6

         // Here we invoke the model with the input we created.
         output, err := model.Invoke(input)
         if err != nil {
             return "", err
         }

         // The output is also specific to the ChatModel interface.
         // Here we return the trimmed content of the first choice.
         return strings.TrimSpace(output.Choices[0].Message.Content), nil
      }
      ```

      ```ts AssemblyScript
      import { models } from "@hypermode/modus-sdk-as"

      import {
        OpenAIChatModel,
        SystemMessage,
        UserMessage,
      } from "@hypermode/modus-sdk-as/models/openai/chat"

      export function generateText(prompt: string): string {
        const model = models.getModel<OpenAIChatModel>("deepseek-reasoner")

        // DeepSeek recommends not using a system prompt and including all instructions in the user prompt
        const input = model.createInput([new UserMessage(prompt)])

        // DeepSeek recommends setting temperature within the range of 0.5-0.7 with 0.6 the recommended default
        input.temperature = 0.6

        // Here we invoke the model with the input we created.
        const output = model.invoke(input)

        // The output is also specific to the OpenAIChatModel interface.
        // Here we return the trimmed content of the first choice.
        return output.choices[0].message.content.trim()
      }
      ```
    </CodeGroup>

    <Info>
      DeepSeek recommends not using a system prompt with DeepSeek-R1 and setting the
      `temperature` parameter in the range of 0.5-0.7
    </Info>
  </Step>

  <Step title="Run your Modus app">
    Run your Modus app locally:

    ```sh
    modus dev
    ```

    This command compiles your Modus app and starts a local GraphQL API endpoint.
  </Step>

  <Step title="Query your function in the Modus API Explorer">
    Open the Modus API Explorer in your web browser at
    `http://localhost:8686/explorer`.

    Add your prompt as an input argument for the `generateText` query field and
    select "Run" to invoke the DeepSeek model.

    ![Querying the DeepSeek model using the Modus API Explorer](https://mintlify.s3.us-west-1.amazonaws.com/hypermode/images/how-to-guides/deepseek/api-explorer-distilled-model.png)

    <Tip>
      For mathematical problems,use a directive in your prompt such as: "Please
      reason step by step, and include your final answer within `\boxed{}.`"
    </Tip>
  </Step>
</Steps>

This example demonstrated how to use the DeepSeek-R1 Distilled Model hosted by
Hypermode in a Modus app to create an endpoint that returns text generated by
the DeepSeek model. More advanced use cases for leveraging the DeepSeek
reasoning models in your Modus app include workflows like tool use / function
calling, generating structured outputs, problem solving, code generation, and
much more. [Let us know](mailto:hello@hypermode.com?subject=DeepSeek+Modus) how
you're leveraging DeepSeek with Modus.

## Using the DeepSeek platform API with Modus

This option involves using the DeepSeek models hosted by DeepSeek Platform with
your Modus app. You'll need to create an account with DeepSeek Platform and pay
for your model usage.

<Steps>
  <Step title="Create a DeepSeek API key">
    Create an account with [DeepSeek Platform](https://platform.deepseek.com).

    Once you've signed in select the "API keys" tab and "Create new API token" to
    generate your DeepSeek Platform API token.

    ![DeepSeek Platform API tokens](https://mintlify.s3.us-west-1.amazonaws.com/hypermode/images/how-to-guides/deepseek/deepseek-platform-api-token.png)
  </Step>

  <Step title="Create a Modus app">
    If you haven't already, create a new modus app. Skip this step if you already have a Modus app.

    ```sh
    modus new
    ```

    <Tip>
      See [the Modus Quickstart](quickstart) for more information about creating
      Modus projects.
    </Tip>
  </Step>

  <Step title="Define the model and connection in your app manifest">
    Update your Modus app's `modus.json` app manifest file to include the DeepSeek
    model and a connection for the DeepSeek Platform API. Use `deepseek-reasoner` as
    the value for `sourceModel` for the DeepSeek-R1 reasoning model and
    `deepseek-chat` for the DeepSeek-V3 model.

    ```json modus.json
    {
      "models": {
        "deepseek-reasoner": {
          "sourceModel": "deepseek-reasoner",
          "connection": "deepseek",
          "path": "v1/chat/completions"
        }
      },
      "connections": {
        "deepseek": {
          "type": "http",
          "baseUrl": "https://api.deepseek.com/",
          "headers": {
            "Authorization": "Bearer {{API_TOKEN}}"
          }
        }
      }
    }
    ```

    <Note>
      At query time, Modus replaces the `{{API_TOKEN}}`secret placeholder with your `MODUS_DEEPSEEK_API_TOKEN` environment variable value.

      Set this environment variable value in the next step.
    </Note>
  </Step>

  <Step title="Create environment variable for your API token">
    Edit the `.env.dev.local` file to declare an environment variable for your DeepSeek Platform API key.

    ```env
    MODUS_DEEPSEEK_API_TOKEN=<YOUR_TOKEN_VALUE_HERE>
    ```

    <Note>
      Modus namespaces environment variables for secrets placeholders with `MODUS` and
      your connection's name from the app manifest. For more details on using secrets
      in Modus, refer to
      [working locally with secrets](/modus/app-manifest#working-locally-with-secrets).
    </Note>
  </Step>

  <Step title="Write a function to invoke the DeepSeek model">
    You can now invoke the model in your Modus app's functions using the Modus
    models interface.

    Here we write a function that takes a prompt as input, invokes the DeepSeek
    model, and returns the generated text as output. At runtime this function
    becomes a GraphQL Query field in the GraphQL API generated by Modus.

    <CodeGroup>
      ```go Go
          package main

          import (
              "strings"

              "github.com/hypermodeinc/modus/sdk/go/pkg/models"
              "github.com/hypermodeinc/modus/sdk/go/pkg/models/openai"
          )

          func GenerateText(prompt string) (string, error) {

              model, err := models.GetModel[openai.ChatModel]("deepseek-reasoner")
              if err != nil {
                  return "", err
              }

              // DeepSeek recommends not using a system prompt and including all instructions in the user prompt
              input, err := model.CreateInput(
                  openai.NewUserMessage(prompt),
              )
              if err != nil {
                  return "", err
              }

              // DeepSeek recommends setting temperature within the range of 0.5-0.7 with 0.6 the recommended default
              input.Temperature = 0.6

              // Here we invoke the model with the input we created.
              output, err := model.Invoke(input)
              if err != nil {
                  return "", err
              }

              // The output is also specific to the ChatModel interface.
              // Here we return the trimmed content of the first choice.
              return strings.TrimSpace(output.Choices[0].Message.Content), nil
          }
      ```

      ```ts AssemblyScript
      import { models } from "@hypermode/modus-sdk-as"

      import {
        OpenAIChatModel,
        SystemMessage,
        UserMessage,
      } from "@hypermode/modus-sdk-as/models/openai/chat"

      export function generateText(prompt: string): string {
        const model = models.getModel<OpenAIChatModel>("deepseek-reasoner")

        // DeepSeek recommends not using a system prompt and including all instructions in the user prompt
        const input = model.createInput([new UserMessage(prompt)])

        // DeepSeek recommends setting temperature within the range of 0.5-0.7 with 0.6 the recommended default
        input.temperature = 0.6

        // Here we invoke the model with the input we created.
        const output = model.invoke(input)

        // The output is also specific to the OpenAIChatModel interface.
        // Here we return the trimmed content of the first choice.
        return output.choices[0].message.content.trim()
      }
      ```
    </CodeGroup>

    <Info>
      DeepSeek recommends not using a system prompt with DeepSeek-R1 and setting the
      `temperature` parameter in the range of 0.5-0.7
    </Info>
  </Step>

  <Step title="Run your Modus app">
    Run your Modus app locally:

    ```sh
    modus dev
    ```

    This command compiles your Modus app and starts a local GraphQL API endpoint.
  </Step>

  <Step title="Query using the Modus API Explorer">
    Open the Modus API Explorer in your web browser at `http://localhost:8686/explorer`.

    Add your prompt as an input argument for the `generateText` query field and
    select "Run" to invoke the DeepSeek model.

    ![Querying the DeepSeek model using the Modus API Explorer](https://mintlify.s3.us-west-1.amazonaws.com/hypermode/images/how-to-guides/deepseek/api-explorer-deepseek-api.png)

    <Tip>
      For mathematical problems,use a directive in your prompt such as: "Please
      reason step by step, and include your final answer within `\boxed{}.`"
    </Tip>
  </Step>
</Steps>

This example demonstrated how to use the DeepSeek Platform API in a Modus app to
create an endpoint that returns text generated by the DeepSeek-R1 model. More
advanced use cases for leveraging the DeepSeek reasoning models in your Modus
app include workflows like tool use / function calling, generating structured
outputs, problem solving, code generation, and much more.
[Let us know](mailto:hello@hypermode.com?subject=DeepSeek+Modus) how you're
leveraging DeepSeek with Modus.

## Resources

* [DeepSeek on Hugging Face](https://huggingface.co/deepseek-ai)
* [`DeepSeek-R1-Distill-Llama-8B` model card](https://huggingface.co/deepseek-ai/DeepSeek-R1-Distill-Llama-8B)
* [DeepSeek-R1 paper](https://github.com/deepseek-ai/DeepSeek-R1/blob/main/DeepSeek_R1.pdf)
* [DeepSeek Platform API docs](https://api-docs.deepseek.com/)


# Error Handling
Source: https://docs.hypermode.com/modus/error-handling

Easily debug and handle errors

Error handling in Modus makes it simple to have both a clear debugging process
for developers and informative responses for end-users.

### Logging errors

The Console API in the Modus SDK is globally available in all functions. It
allows developers to capture log messages and errors, which are automatically
included in Modus runtime execution logs.

<Tip>
  When deployed to Hypermode, function logs are available in the Hypermode
  Console on the [Function Runs](../observe-functions#function-runs) page.
</Tip>

The Console API provides five logging functions:

```go
console.log("This is a simple log message.")
console.debug("This is a debug message.")
console.info("This is an info message.")
console.warn("This is a warning message.")
console.error("This is an error message.")
```

### Error reporting in GraphQL

GraphQL responses have a standard structure that includes both `data` and
`errors` sections. Modus allows for the inclusion of error codes or messages
within the `errors` section to allow for downstream processing in addition to
debugging.

<CodeGroup>
  ```ts Go
  // in Go, error handling is typically done by returning an `error` object as the
  // last result of a function; Modus transforms this into logging and error handling
  // automatically, ensuring all errors are logged before being sent to the response
  func TestError(input string) (string, error) {
      if input == "" {
          return "", errors.New("input is empty")
      }
      return "You said: " + input, nil
  }
  ```

  ```ts AssemblyScript
  export function TestError(input: string): string {
    if (input == "") {
      console.error("input is empty")
      // this is a non-fatal error reported in GraphQL response.
      // the function continues
      return "Can't process your input"
    }

    if (input == "error") {
      throw new Error(`This is a fatal error.`)
      // a fatal error appears in the log
      // the errors section in GraphQL responses contains only one entry with
      // "message": "error calling function" and the data section is empty
      // the function does not continue
    }

    return "You said: " + input
  }
  ```
</CodeGroup>

### Best practices for error handling

* **Handle non-fatal errors** using `console.error`, allowing the function to
  continue. The GraphQL response may have both a `data` section and an `errors`
  section.

* **Handle critical errors** using AssemblyScript `throw` keyword or the Go
  idiomatic error object to stop the function's execution.

* **Return clear error messages**: When returning errors, include concise and
  informative error messages that help diagnose the issue.


# Model Invoking
Source: https://docs.hypermode.com/modus/model-invoking

Invoke your models with the Modus Models API

Modus enables you to easily integrate AI models into your app. In just a few
steps, you can generate text, classify items, compute embeddings, and use models
in your app for many other use cases using the `models` API in the Modus SDK.

## Understanding key components

**Models**: your app can invoke models hosted on Hypermode, OpenAI, Anthropic,
and many more. You define models in your app manifest.

**Models API**: the `models` API in the Modus SDK provides a set of functions
that you can import and call from your app.

## Define your models

You define models in your [app manifest](./app-manifest#models). Here are some
examples:

<CodeGroup>
  ```json Llama-3.1-8B-Instruct {4-9}
  {
    ...
    "models": {
      // model card: https://huggingface.co/meta-llama/Llama-3.2-3B-Instruct
      "text-generator": {
        "sourceModel": "meta-llama/Llama-3.2-3B-Instruct", // model name on the provider
        "provider": "hugging-face", // provider for this model
        "connection": "hypermode" // host where the model is running
      }
    }
    ...
  }
  ```

  ```json GPT-4o {4-9,13-19}
  {
    ...
    "models": {
      // model docs: https://platform.openai.com/docs/models/gpt-4o
      "text-generator": {
        "sourceModel": "gpt-4o",
        "connection": "openai",
        "path": "v1/chat/completions"
      }
    },
    // for externally hosted models, explicitly define the connection
    "connections": {
      "openai": {
        "type": "http",
        "baseUrl": "https://api.openai.com/",
        "headers": {
          "Authorization": "Bearer {{API_KEY}}"
        }
      }
    }
    ...
  }
  ```

  ```json Claude 3.5 Sonnet {4-9,13-20}
  {
    ...
    "models": {
      // model docs: https://docs.anthropic.com/en/docs/about-claude/models#model-comparison-table
      "text-generator": {
        "sourceModel": "claude-3-5-sonnet-20240620",
        "connection": "anthropic",
        "path": "v1/messages"
      }
    },
    // for externally hosted models, explicitly define the connection
    "connections": {
      "anthropic": {
        "type": "http",
        "baseUrl": "https://api.anthropic.com/",
        "headers": {
          "x-api-key": "{{API_KEY}}",
          "anthropic-version": "2023-06-01"
        }
      }
    }
    ...
  }
  ```
</CodeGroup>

## Invoking a model for inference

To invoke a model within your app, import the `models` packages from the SDK.
Import the core `models` package and the package for the interface your model
uses. For example, to use the OpenAI interface for a text-generation model, you
would import the `openai` package in addition to the core `models` package.

### Generation models

Generation models are models that generate text, images, or other data based on
input. Currently, the Models API supports the OpenAI, Anthropic, and Gemini
interfaces. Let's see how to invoke a model using the OpenAI interface.

When using a model interface, you automatically get type-ahead guidance in your
code editor based on the available options for that interface.

<Note>
  Hypermode-hosted generation models implement the OpenAI API standard. To
  interact with these models, use the `openai` interface.
</Note>

<CodeGroup>
  ```go Go
  package main

  import (
      "encoding/json"
      "fmt"
      "strings"

      "github.com/hypermodeinc/modus/sdk/go/pkg/models"
      "github.com/hypermodeinc/modus/sdk/go/pkg/models/openai"
  )

  // this model name should match the one defined in the modus.json manifest file
  const modelName = "text-generator"

  func GenerateText(instruction, prompt string) (string, error) {
      model, err := models.GetModel[openai.ChatModel](modelName)
      if err != nil {
          return "", err
      }

      input, err := model.CreateInput(
          openai.NewSystemMessage(instruction),
          openai.NewUserMessage(prompt),
      )
      if err != nil {
          return "", err
      }

      // this is one of many optional parameters available for the OpenAI chat interface
      input.Temperature = 0.7

      output, err := model.Invoke(input)
      if err != nil {
          return "", err
      }

      return strings.TrimSpace(output.Choices[0].Message.Content), nil
  }
  ```

  ```ts AssemblyScript
  import { models } from "@hypermode/modus-sdk-as"
  import {
    OpenAIChatModel,
    ResponseFormat,
    SystemMessage,
    UserMessage,
  } from "@hypermode/modus-sdk-as/models/openai/chat"

  // this model name should match the one defined in the modus.json manifest file
  const modelName: string = "text-generator"

  export function generateText(instruction: string, prompt: string): string {
    const model = models.getModel<OpenAIChatModel>(modelName)
    const input = model.createInput([
      new SystemMessage(instruction),
      new UserMessage(prompt),
    ])

    // this is one of many optional parameters available for the OpenAI chat interface
    input.temperature = 0.7

    const output = model.invoke(input)
    return output.choices[0].message.content.trim()
  }
  ```
</CodeGroup>

### Classification models

Classification models provide a label for input data. You can use these models
to sort data into categories or classes. Let's see how to invoke a
classification model.

<CodeGroup>
  ```go Go

  import (
    "errors"
    "fmt"

    "github.com/hypermodeinc/modus/sdk/go/pkg/models"
    "github.com/hypermodeinc/modus/sdk/go/pkg/models/experimental"
  )

  // this model name should match the one defined in the modus.json manifest file
  const modelName = "my-classifier"

  // this function takes input text and a probability threshold, and returns the
  // classification label determined by the model, if the confidence is above the
  // threshold; otherwise, it returns an empty string
  func ClassifyText(text string, threshold float32) (string, error) {
    predictions, err := classify(text)
    if err != nil {
      return "", err
    }

    prediction := predictions[0]
    if prediction.Confidence < threshold {
      return "", nil
    }

    return prediction.Label, nil
  }
  ```

  ```ts AssemblyScript
  import { models } from "@hypermode/modus-sdk-as"
  import {
    ClassificationModel,
    ClassifierResult,
  } from "@hypermode/modus-sdk-as/models/experimental/classification"

  // this model name should match the one defined in the modus.json manifest file
  const modelName: string = "my-classifier"

  // this function takes input text and a probability threshold, and returns the
  // classification label determined by the model, if the confidence is above the
  // threshold; otherwise, it returns an empty string
  export function classifyText(text: string, threshold: f32): string {
    const model = models.getModel<ClassificationModel>(modelName)
    const input = model.createInput([text])
    const output = model.invoke(input)

    const prediction = output.predictions[0]
    if (prediction.confidence >= threshold) {
      return prediction.label
    }

    return ""
  }
  ```
</CodeGroup>

### Embedding models

Modus supports invoking embedding models for text, images, and other data types.
You use the outputs of these models for implementing search, recommendation, and
similarity functions in your app. Refer to [Search](/modus/search) for more
information on how to use embeddings in your app.


# Modus CLI
Source: https://docs.hypermode.com/modus/modus-cli

Comprehensive reference for the Modus CLI commands and usage

The Modus CLI is a command-line tool for interacting with your Modus app and
running it locally.

## Install

Install Modus CLI via npm.

```bash
npm install -g @hypermode/modus-cli
```

<Info>
  The Modus CLI automatically downloads various files and dependencies to the
  following directory:

  * Linux/macOS: `$HOME/.modus`
  * Windows: `%USERPROFILE%/.modus`

  If you would like to override the location of this directory, you can set the
  `MODUS_HOME` environment variable to the desired path.

  For example, if your local permissions on Windows don't allow creating a
  directory in the root of your user profile, you can try a different location.
  You can use the `AppData` directory, or any other directory where you have write
  permissions.

  ```cmd
  setx MODUS_HOME %APPDATA%\Modus
  ```

  *Note, the Windows `setx` command makes the environment variable setting
  permanent.*
</Info>

## Commands

### `new`

Initialize a new Modus app. The Modus CLI prompts you to enter the app name and
language of choice.

### `dev`

Run your Modus app locally. The Modus CLI starts a local server and provides a
URL to access the app.

<Tip>
  When using [Hyp CLI](/hyp-cli) alongside the Modus CLI, users get access to
  [Hypermode-hosted models](/hosted-models) for local development.
</Tip>

### `build`

Build your Modus app. The Modus CLI compiles your app and generates a `.build`
folder for the artifacts.

### `uninstall`

Uninstall the Modus CLI from your system.


# Overview
Source: https://docs.hypermode.com/modus/overview

Welcome to the Modus docs!

## What is Modus? {/* vale Google.Contractions = NO */}

Modus is an open source, serverless framework for building functions and APIs,
powered by WebAssembly.

You write your app logic in Go or AssemblyScript, and Modus provides additional
features to easily integrate models, data, and external services.

To **build apps that are thoughtful, fun, and effective**, we often need to
integrate models in different forms, whether generative large language models or
classical machine/deep learning models.

Your app might be a simple create, read, update, and delete (CRUD) function that
has a single model to identify similar entries. Or, it could be a complex
agentic reasoning system that chains dozens of models and data sources together.
**Modus creates a way of working with models that scales with your needs.**

Modus exists to make it easier for you to build the apps of your dreams.

<Note>
  Modus is a multi-language framework. It currently includes support for Go and
  AssemblyScript, a WebAssembly compatible TypeScript-like language. Additional
  language support is in development.
</Note>

## What is Modus good for? {/* vale Google.Contractions = NO */}

We designed Modus primarily as a general-purpose app framework, it just happens
to treat models as a first-class component. With Modus you can use models, as
appropriate, without additional complexity.

However, Modus is best for applications that require sub-second response times.
We've made trade-offs to optimize for speed and simplicity.

For more inspiration, check out the
[Modus recipes](https://github.com/hypermodeinc/modus-recipes).

## Main features

A few of the core Modus features include:

| Feature                                     | Description                                                                                  |
| ------------------------------------------- | -------------------------------------------------------------------------------------------- |
| [Multi-Language](/modus/project-structure)  | Write functions in Go and AssemblyScript, with additional language support in development    |
| [Auto-Generated API](/modus/api-generation) | A secure API is automatically generated from your function signatures                        |
| [Model Integration](/modus/model-invoking)  | Connect and invoke AI models from different providers, without learning a new SDK            |
| [Search](/modus/search)                     | Add natural language search and recommendations with integrated vector embeddings            |
| [Authentication](/modus/authentication)     | Secure your API endpoints with minimal configuration                                         |
| **WebAssembly Runtime**                     | Small and portable execution engine for deployment across server, edge, and desktop computes |


# Project Structure
Source: https://docs.hypermode.com/modus/project-structure

Understand the structure of a Modus app

{/* vale Google.Passive = NO */}

A Modus app is organized into a set of files and directories that define the
structure of your app. This structure is important for maintaining and scaling
your app as it grows.

{/* vale Google.Passive = YES */}

## Structure

Modus fits within the natural language structure of your app code, with
configuration separated from your source code.

<CodeGroup>
  ```bash Go
  .
  ├── main.go
  ├── ...
  ├── modus.json
  ├── go.mod
  └── go.sum
  ```

  ```bash AssemblyScript
  .
  ├── assembly
      ├── index.ts
      ├── ...
      └── tsconfig.json
  ├── modus.json
  ├── asconfig.json
  ├── package.json
  └── package-lock.json
  ```
</CodeGroup>

## App manifest

The `modus.json` [app manifest](/modus/app-manifest) is the central
configuration file for your Modus app. It defines the endpoints, connections,
models, and collections that your code has available to it during runtime.
Because Modus is a secure-by-default framework, only the resources defined in
this file are accessible to your app.

## Initializing your app

When you initialize your app with the `modus new` command, the Modus CLI
scaffolds your app with the necessary files and directories.


# Quickstart
Source: https://docs.hypermode.com/modus/quickstart

Run your first Modus app in a few minutes

In this quickstart we'll show you how to get set up with Modus and its CLI and
build a simple app that fetches a random quote from an external API. You'll
learn how to use the basic components of a Modus app and how to run it locally.

## Prerequisites

* [Node.js](https://nodejs.org/en/download/package-manager) - v22 or higher
* Text editor - we recommend [VS Code](https://code.visualstudio.com/)
* Terminal - access Modus through a command-line interface (CLI)

## Building your first Modus app

<Steps>
  <Step title="Install the Modus CLI">
    The Modus CLI provides a set of commands to help you create, build, and run your Modus apps.
    Install the CLI using npm.

    ```bash
    npm install -g @hypermode/modus-cli
    ```
  </Step>

  <Step title="Initialize your Modus app">
    To create a new Modus app, run the following command in your terminal:

    ```bash
    modus new
    ```

    This command prompts you to choose between Go and AssemblyScript as the language for your app. It
    then creates a new directory with the necessary files and folders for your app. You will also be asked if you would like to initialize a Git repository.
  </Step>

  <Step title="Build and run your app">
    To build and run your app, navigate to the app directory and run the following command:

    ```bash
    modus dev
    ```

    This command runs your app locally in development mode and provides you with a URL to access your
    app's generated API.
  </Step>

  <Step title="Access your local endpoint">
    Once your app is running, you can access the graphical interface for your API at the URL located in your terminal.

    ```bash
    View endpoint: http://localhost:8686/explorer
    ```

    The API Explorer interface allows you to interact with your app's API and test your functions.

    <img className="block" src="https://mintlify.s3.us-west-1.amazonaws.com/hypermode/images/api-explorer.png" alt="API Graphical Interface." />
  </Step>

  <Step title="Add a connection">
    Modus is a secure-by-default framework. To connect to external services, you need to add a connection
    in your app manifest.

    Add the following code into your `modus.json` manifest file:

    ```json modus.json
    {
      "connections": {
        "zenquotes": {
          "type": "http",
          "baseUrl": "https://zenquotes.io/"
        }
      }
    }
    ```
  </Step>

  <Step title="Add a function">
    Functions are the building blocks of your app. Let's add a function that fetches a random quote from
    the ZenQuotes connection you just created.

    <Tabs>
      <Tab title="Go">
        To add a function, create a new file in the root directory with the following code:

        ```go quotes.go
        package main

        import (
          "errors"
          "fmt"

          "github.com/hypermodeinc/modus/sdk/go/pkg/http"
        )

        type Quote struct {
          Quote  string `json:"q"`
          Author string `json:"a"`
        }

        // this function makes a request to an API that returns data in JSON format, and
        // returns an object representing the data
        func GetRandomQuote() (*Quote, error) {
          request := http.NewRequest("https://zenquotes.io/api/random")

          response, err := http.Fetch(request)
          if err != nil {
            return nil, err
          }
          if !response.Ok() {
            return nil, fmt.Errorf("Failed to fetch quote. Received: %d %s", response.Status, response.StatusText)
          }

          // the API returns an array of quotes, but we only want the first one
          var quotes []Quote
          response.JSON(&quotes)
          if len(quotes) == 0 {
            return nil, errors.New("expected at least one quote in the response, but none were found")
          }
          return &quotes[0], nil
        }
        ```
      </Tab>

      <Tab title="AssemblyScript">
        To add a function, create a new file in the `assembly` directory with the following code:

        ```ts quotes.ts
        import { http } from "@hypermode/modus-sdk-as";

        @json
        class Quote {
          @alias("q")
          quote!: string;

          @alias("a")
          author!: string;
        }

        // this function makes a request to an API that returns data in JSON format, and
        // returns an object representing the data
        export function getRandomQuote(): Quote {
          const request = new http.Request("https://zenquotes.io/api/random");

          const response = http.fetch(request);
          if (!response.ok) {
            throw new Error(
              `Failed to fetch quote. Received: ${response.status} ${response.statusText}`,
            );
          }

          // the API returns an array of quotes, but we only want the first one
          return response.json<Quote[]>()[0];
        }
        ```

        Then add the following to `index.ts`. This includes the `getRandomQuote` function on
        your generated API.

        ```ts index.ts
        export * from "./quotes";
        ```
      </Tab>
    </Tabs>

    After adding your function, you can use the API Explorer interface to test the `GetRandomQuote` function.
  </Step>

  <Step title="Add a model">
    Modus also supports AI models. You can define new models in your `modus.json` file. Let's add a new meta-llama model:

    ```json
      "models": {
        "text-generator": {
          "sourceModel": "meta-llama/Llama-3.2-3B-Instruct",
          "provider": "hugging-face",
          "connection": "hypermode"
        }
      },
    ```
  </Step>

  <Step title="Install the Hyp CLI and log in">
    Next, install the Hyp CLI. This allows you to access hosted models on the Hypermode platform.

    ```bash
      npm install -g @hypermode/hyp-cli
    ```

    You can now use the `hyp login` command to log in to the Hyp CLI.
    This links your project to the Hypermode platform, allowing you to leverage the model in your modus app.
  </Step>

  <Step title="Track local model inferences">
    When testing an AI app locally, Modus records the inference and related metadata
    in the `View Inferences` tab of the APIs explorer.

    <Note>
      Local model tracing is only supported on Linux and macOS. Windows support is
      coming soon.
    </Note>

    ![local model tracing](https://mintlify.s3.us-west-1.amazonaws.com/hypermode/images/observe-functions/local-inference-history.png)
  </Step>
</Steps>

<Tip>
  For more inspiration, check out the [Modus
  recipes](https://github.com/hypermodeinc/modus-recipes).
</Tip>


# Run Locally
Source: https://docs.hypermode.com/modus/run-locally

Test your Modus app and iterate quickly

Modus provides a local development environment that makes it easy to build and
test your app, with local access to models.

## Launching your app in development mode

To run your app, from the project root, run:

```bash
modus dev
```

The `modus dev` command compiles your app code, starts a local server, and
provides a URL to access your app's API. It also enables fast refresh, which
automatically recompiles and reloads any changed functions while preserving app
state during development.

Once your app is running, you can access the graphical interface for your API at
the URL located in your terminal.

```bash
View endpoint: http://localhost:8686/explorer
```

The API Explorer interface allows you to interact with your app's API and test
your functions.

<img className="block" src="https://mintlify.s3.us-west-1.amazonaws.com/hypermode/images/api-explorer.png" alt="API Graphical Interface." />

## Environment secrets

When you run your app locally using `modus dev`, the runtime replaces the
placeholders of the manifest with values from environment variables defined in
your operating system or in `.env` files.

The environment variables keys must be upper case and follow the naming
convention:

`MODUS_<CONNECTION NAME>_<PLACEHOLDER>`

For example, with the following manifest:

```json modus.json
{
  "connections": {
    "openai": {
      "type": "http",
      "baseUrl": "https://api.openai.com/",
      "headers": {
        "Authorization": "Bearer {{API_KEY}}"
      }
    }
  }
}
```

The Modus runtime substitutes `{{API_KEY}}` with the value of the environment
variable `MODUS_OPENAI_API_KEY`

An easy way to define the environment variables when working locally is to use
the file `.env.dev.local` located in your app folder.

For the previous manifest, we can set the key in the .env.dev.local file as
follow:

```text .env.dev.local
MODUS_OPENAI_API_KEY="your openai key"
```

<Warning>
  You should exclude `.env` files from source control. Projects created with
  `modus new` exclude these files automatically when creating your project.
</Warning>

## Using Hypermode-hosted models

To use Hypermode-hosted models in your local environment, first install the Hyp
CLI:

```bash
npm install -g @hypermode/hyp-cli
```

Then log in to your Hypermode account:

```bash
hyp login
```

After logging in, your app automatically connects to Hypermode-hosted models
when running locally. For more information on the models available to use, see
[hosted shared models](/hosted-models#shared-models).

## Working with Collections

Collections requires a PostgreSQL instance for local development. While
Hypermode manages this database in production, you'll need to set up PostgreSQL
locally when developing outside the Hypermode platform. For detailed setup
instructions, see
[Develop locally with Collections](/modus/search#develop-locally-with-collections).


# Collections APIs
Source: https://docs.hypermode.com/modus/sdk/assemblyscript/collections

Add storage and vector search capabilities to your functions.

export const SdkHeader = ({language, feature}) => <Note>
    <p>
      While each Modus SDK offers similar capabilities, the APIs and usage may
      vary between languages.
    </p>
    <p>
      Modus {feature} APIs documentation is available on the following pages:
    </p>
    <ul>
      {(() => {
  const languages = ["AssemblyScript", "Go"];
  const page = feature.toLowerCase().replace(/\W/g, "");
  return languages.map(lang => {
    if (lang === language) {
      return <li>
                <b>
                  {lang} {feature} APIs
                </b>{" "}
                (this page)
              </li>;
    } else {
      return <li>
                <a href={`../${lang.toLowerCase()}/${page}`}>
                  {lang} {feature} APIs
                </a>
              </li>;
    }
  });
})()}
    </ul>
  </Note>;

<SdkHeader language="AssemblyScript" feature="Collections" />

The Modus Collection APIs allow you to add vector search within your functions.

## Import

To begin, import the `collections` namespace from the SDK:

```ts
import { collections } from "@hypermode/modus-sdk-as"
```

## Collections APIs

{/* vale Google.Headings = NO */}

The APIs in the `collections` namespace are below, organized by category.

<Tip>
  We're constantly introducing new APIs through ongoing development with early
  users. Please [open an issue](https://github.com/hypermodeinc/modus/issues) if
  you have ideas on what would make Modus even more powerful for your next app!
</Tip>

### Mutation Functions

#### upsert

Inserts or updates an item in a collection.

<Note>
  If the item already exists, the function overwrites the previous value. If
  not, it creates a new one.
</Note>

```ts
function upsert(
  collection: string,
  key: string | null,
  text: string,
  labels: string[] = [],
  namespace: string = "",
): CollectionMutationResult
```

<ResponseField name="collection" type="string" required>
  Name of the collection, as [defined in the
  manifest](/modus/app-manifest#collections).
</ResponseField>

<ResponseField name="key" type="string">
  The unique identifier for the item in the namespace. If `null`, the function
  generates a unique identifier.
</ResponseField>

<ResponseField name="text" type="string" required>
  The text of the item to add to the collection.
</ResponseField>

<ResponseField name="labels" type="string[]">
  An optional array of labels to associate with the item.
</ResponseField>

<ResponseField name="namespace" type="string">
  Associates the item with a specific namespace. Defaults to an empty namespace
  if not provided.
</ResponseField>

#### upsertBatch

Inserts or updates a batch of items into a collection.

<Note>
  If an item with the same key already exists, the original text is overwritten
  with the new text.
</Note>

```ts
function upsertBatch(
  collection: string,
  keys: string[] | null,
  texts: string[],
  labelsArr: string[][] = [],
  namespace: string = "",
): CollectionMutationResult
```

<ResponseField name="collection" type="string" required>
  Name of the collection, as [defined in the
  manifest](/modus/app-manifest#collections).
</ResponseField>

<ResponseField name="keys" type="string[]">
  Array of keys for the item to add to the collection. If you pass `null` for
  any key, Hypermode assigns a new UUID as the key for the item.
</ResponseField>

<ResponseField name="texts" type="string[]" required>
  Array of texts for the items to add to the collection.
</ResponseField>

<ResponseField name="labelsArr" type="string[][]">
  An optional array of arrays of labels to associate with the items.
</ResponseField>

<ResponseField name="namespace" type="string">
  Associates the item with a specific namespace. Defaults to an empty namespace
  if not provided.
</ResponseField>

#### remove

Removes an item from the collection.

```ts
function remove(
  collection: string,
  key: string,
  namespace: string = "",
): CollectionMutationResult
```

<ResponseField name="collection" type="string" required>
  Name of the collection, as [defined in the
  manifest](/modus/app-manifest#collections).
</ResponseField>

<ResponseField name="key" type="string" required>
  The key of the item to delete from the collection.
</ResponseField>

<ResponseField name="namespace" type="string">
  The namespace to remove the item from. Defaults to the default namespace if
  not provided.
</ResponseField>

### Search and Retrieval Functions

#### computeDistance

Computes distance between two keys in a collection using a search method's
embedder.

```ts
function computeDistance(
  collection: string,
  searchMethod: string,
  key1: string,
  key2: string,
  namespace: string = "",
): CollectionSearchResultObject
```

<ResponseField name="collection" type="string" required>
  Name of the collection, as [defined in the
  manifest](/modus/app-manifest#collections).
</ResponseField>

<ResponseField name="searchMethod" type="string" required>
  The search method used to calculate embedding for key's texts.
</ResponseField>

<ResponseField name="key1, key2" type="string" required>
  Keys to compute similarity on.
</ResponseField>

<ResponseField name="namespace" type="string">
  The namespace to search the items from. Defaults to the default namespace if
  not provided.
</ResponseField>

#### getLabels

Get the labels for an item in a collection.

```ts
function getLabels(
  collection: string,
  key: string,
  namespace: string = "",
): string[]
```

<ResponseField name="collection" type="string" required>
  Name of the collection, as [defined in the
  manifest](/modus/app-manifest#collections).
</ResponseField>

<ResponseField name="key" type="string" required>
  The key of the item to retrieve.
</ResponseField>

<ResponseField name="namespace" type="string">
  The namespace to get the item from. Defaults to the default namespace if not
  provided.
</ResponseField>

#### getNamespaces

Get all namespaces in a collection.

```ts
function getNamespaces(collection: string): string[]
```

<ResponseField name="collection" type="string" required>
  Name of the collection, as [defined in the
  manifest](/modus/app-manifest#collections).
</ResponseField>

#### getText

Gets an item's text from a collection, give the item's key.

```ts
function getText(
  collection: string,
  key: string,
  namespace: string = "",
): string
```

<ResponseField name="collection" type="string" required>
  Name of the collection, as [defined in the
  manifest](/modus/app-manifest#collections).
</ResponseField>

<ResponseField name="key" type="string" required>
  The key of the item to retrieve.
</ResponseField>

<ResponseField name="namespace" type="string">
  The namespace to get the item from. Defaults to the default namespace if not
  provided.
</ResponseField>

#### getTexts

Get all items from a collection. The result is a map of key to text for all
items in the collection.

```ts
function getTexts(
  collection: string,
  namespace: string = "",
): Map<string, string>
```

<ResponseField name="collection" type="string" required>
  Name of the collection, as [defined in the
  manifest](/modus/app-manifest#collections).
</ResponseField>

<ResponseField name="namespace" type="string">
  The namespace to get the items from. Defaults to the default namespace if not
  provided.
</ResponseField>

#### getVector

Get the vector for an item in a collection.

```ts
function getVector(
  collection: string,
  searchMethod: string,
  key: string,
  namespace: string = "",
): f32[]
```

<ResponseField name="collection" type="string" required>
  Name of the collection, as [defined in the
  manifest](/modus/app-manifest#collections).
</ResponseField>

<ResponseField name="searchMethod" type="string" required>
  The search method used to calculate embedding for key's texts.
</ResponseField>

<ResponseField name="key" type="string" required>
  The key of the item to retrieve.
</ResponseField>

<ResponseField name="namespace" type="string">
  The namespace to get the item from. Defaults to the default namespace if not
  provided.
</ResponseField>

#### nnClassify

Classify an item in the collection using previous vectors' labels.

```ts
function nnClassify(
  collection: string,
  searchMethod: string,
  text: string,
  namespace: string = "",
): CollectionClassificationResult
```

<ResponseField name="collection" type="string" required>
  Name of the collection, as [defined in the
  manifest](/modus/app-manifest#collections).
</ResponseField>

<ResponseField name="searchMethod" type="string" required>
  The search method used to calculate embedding for text & search against.
</ResponseField>

<ResponseField name="text" type="string" required>
  The text to compute natural language search on.
</ResponseField>

<ResponseField name="namespace" type="string">
  The namespace to search the items from. Defaults to the default namespace if
  not provided.
</ResponseField>

#### search

Perform a natural language search on items within a collection. This method is
useful for finding items that match a search query based on semantic meaning.

<Note>
  Modus uses the same embedder for both inserting text into the collection, and
  for the text used when searching the collection.
</Note>

```ts
function search(
  collection: string,
  searchMethod: string,
  text: string,
  limit: i32,
  returnText: bool = false,
  namespaces: string[] = [],
): CollectionSearchResult
```

<ResponseField name="collection" type="string" required>
  Name of the collection, as [defined in the
  manifest](/modus/app-manifest#collections).
</ResponseField>

<ResponseField name="searchMethod" type="string" required>
  The search method used to calculate embedding for text & search against.
</ResponseField>

<ResponseField name="text" type="string" required>
  The text to compute natural language search on.
</ResponseField>

<ResponseField name="limit" type="i32" required>
  The number of result objects to return.
</ResponseField>

<ResponseField name="returnText" type="bool">
  A flag to return the texts in the response.
</ResponseField>

<ResponseField name="namespaces" type="string[]">
  A list of namespaces to search the item from. Defaults to the default
  namespace if not provided.
</ResponseField>

#### searchByVector

Perform a vector-based search on a collection, which is helpful for scenarios
requiring precise similarity calculations between pre-computed embeddings.

<Note>
  Modus uses the same embedder for both inserting text into the collection, and
  for the vector used when searching the collection.
</Note>

```ts
function searchByVector(
  collection: string,
  searchMethod: string,
  vector: f32[],
  limit: i32,
  returnText: bool = false,
  namespaces: string[] = [],
): CollectionSearchResult
```

<ResponseField name="collection" type="string" required>
  Name of the collection, as [defined in the
  manifest](/modus/app-manifest#collections).
</ResponseField>

<ResponseField name="searchMethod" type="string" required>
  The search method used to calculate embedding for vector & search against.
</ResponseField>

<ResponseField name="vector" type="f32[]" required>
  The vector to compute search on.
</ResponseField>

<ResponseField name="limit" type="i32" required>
  The number of result objects to return.
</ResponseField>

<ResponseField name="returnText" type="bool">
  A flag to return the texts in the response.
</ResponseField>

<ResponseField name="namespaces" type="string[]">
  An optional array of namespaces to search within.
</ResponseField>

### Maintenance Functions

#### recomputeSearchMethod

Recalculates the embeddings for all items in a collection. It can be
resource-intensive, use it when necessary, for example after you have updated
the method for embedding calculation and want to re-compute the embeddings for
existing data in the collection.

```ts
function recomputeSearchMethod(
  collection: string,
  searchMethod: string,
  namespace: string = "",
): SearchMethodMutationResult
```

<ResponseField name="collection" type="string" required>
  Name of the collection, as [defined in the
  manifest](/modus/app-manifest#collections).
</ResponseField>

<ResponseField name="searchMethod" type="string" required>
  The search method to recompute embeddings for.
</ResponseField>

<ResponseField name="namespace" type="string">
  The namespace to use. Defaults to the default namespace if not provided.
</ResponseField>

### Types

#### CollectionMutationResult

Represents the result of a mutation operation on a collection.

```ts
class CollectionMutationResult {
  collection: string
  status: CollectionStatus
  error: string
  isSuccessful: bool
  operation: string
  keys: string[]
}
```

<ResponseField name="collection" type="string">
  Name of the collection.
</ResponseField>

<ResponseField name="status" type="CollectionStatus">
  The status of the operation.
</ResponseField>

<ResponseField name="error" type="string">
  Error message, if any.
</ResponseField>

<ResponseField name="isSuccessful" type="bool">
  A boolean indicating whether the operation completed successfully. Use this to
  confirm success before handling the result.
</ResponseField>

<ResponseField name="operation" type="string">
  The operation performed.
</ResponseField>

<ResponseField name="keys" type="string[]">
  The keys of the items affected by the operation.
</ResponseField>

#### CollectionClassificationLabelObject

Represents a classification label.

```ts
class CollectionClassificationLabelObject {
  label: string
  confidence: f64
}
```

<ResponseField name="label" type="string">
  The classification label.
</ResponseField>

<ResponseField name="confidence" type="f64">
  The confidence score of the classification label.
</ResponseField>

#### CollectionClassificationResult

Represents the result of a classification operation on a collection.

```ts
class CollectionClassificationResult {
  collection: string
  status: CollectionStatus
  error: string
  isSuccessful: bool
  searchMethod: string
  labelsResult: CollectionClassificationLabelObject[]
  cluster: CollectionClassificationResultObject[]
}
```

<ResponseField name="collection" type="string">
  Name of the collection.
</ResponseField>

<ResponseField name="status" type="CollectionStatus">
  The status of the operation.
</ResponseField>

<ResponseField name="error" type="string">
  Error message, if any.
</ResponseField>

<ResponseField name="isSuccessful" type="bool">
  A boolean indicating whether the operation completed successfully. Use this to
  confirm success before handling the result.
</ResponseField>

<ResponseField name="searchMethod" type="string">
  The search method used in the operation.
</ResponseField>

<ResponseField name="labelsResult" type="CollectionClassificationLabelObject[]">
  The classification labels.
</ResponseField>

<ResponseField name="cluster" type="CollectionClassificationResultObject[]">
  The classification results.
</ResponseField>

#### CollectionClassificationResultObject

Represents an object in the classification results.

```ts
class CollectionClassificationResultObject {
  key: string
  labels: string[]
  distance: f64
  score: f64
}
```

<ResponseField name="key" type="string">
  The key of the item classified.
</ResponseField>

<ResponseField name="labels" type="string[]">
  The classification labels.
</ResponseField>

<ResponseField name="distance" type="f64">
  The distance of the item from the classification labels.
</ResponseField>

<ResponseField name="score" type="f64">
  The similarity score of the item classified.
</ResponseField>

#### CollectionSearchResult

Represents the result of a search operation on a collection.

```ts
class CollectionSearchResult {
  collection: string
  status: CollectionStatus
  error: string
  isSuccessful: bool
  searchMethod: string
  objects: CollectionSearchResultObject[]
}
```

<ResponseField name="collection" type="string">
  Name of the collection.
</ResponseField>

<ResponseField name="status" type="CollectionStatus">
  The status of the operation.
</ResponseField>

<ResponseField name="error" type="string">
  Error message, if any.
</ResponseField>

<ResponseField name="isSuccessful" type="bool">
  A boolean indicating whether the operation completed successfully. Use this to
  confirm success before handling the result.
</ResponseField>

<ResponseField name="searchMethod" type="string">
  The search method used in the operation.
</ResponseField>

<ResponseField name="objects" type="CollectionSearchResultObject[]">
  The search results.
</ResponseField>

#### CollectionSearchResultObject

Represents an object in the search results.

```ts
class CollectionSearchResultObject {
  namespace: string
  key: string
  text: string
  labels: string[]
  distance: f64
  score: f64
}
```

<ResponseField name="namespace" type="string">
  The namespace of the item found as part of the search.
</ResponseField>

<ResponseField name="key" type="string">
  The key of the item found as part of the search.
</ResponseField>

<ResponseField name="text" type="string">
  The text of the item found as part of the search.
</ResponseField>

<ResponseField name="distance" type="f64">
  The distance of the item from the search text.
</ResponseField>

<ResponseField name="score" type="f64">
  The similarity score of the item found, as it pertains to the search.
</ResponseField>

#### CollectionStatus

The status of a collection operation.

```ts
enum CollectionStatus {
  Success = "success"
  Error = "error"
}
```

<ResponseField name="Success" type="string">
  The operation was successful.
</ResponseField>

<ResponseField name="Error" type="string">
  The operation encountered an error.
</ResponseField>

#### SearchMethodMutationResult

Represents the result of a mutation operation on a search method.

```ts
class SearchMethodMutationResult {
  collection: string
  status: CollectionStatus
  error: string
  isSuccessful: bool
  operation: string
  searchMethod: string
}
```

<ResponseField name="collection" type="string">
  Name of the collection.
</ResponseField>

<ResponseField name="status" type="CollectionStatus">
  The status of the operation.
</ResponseField>

<ResponseField name="error" type="string">
  Error message, if any.
</ResponseField>

<ResponseField name="isSuccessful" type="bool">
  A boolean indicating whether the operation completed successfully. Use this to
  confirm success before handling the result.
</ResponseField>

<ResponseField name="operation" type="string">
  The operation performed.
</ResponseField>

<ResponseField name="searchMethod" type="string">
  The search method affected by the operation.
</ResponseField>


# Console APIs
Source: https://docs.hypermode.com/modus/sdk/assemblyscript/console

Capture errors and debugging information in your functions

export const SdkHeader = ({language, feature}) => <Note>
    <p>
      While each Modus SDK offers similar capabilities, the APIs and usage may
      vary between languages.
    </p>
    <p>
      Modus {feature} APIs documentation is available on the following pages:
    </p>
    <ul>
      {(() => {
  const languages = ["AssemblyScript", "Go"];
  const page = feature.toLowerCase().replace(/\W/g, "");
  return languages.map(lang => {
    if (lang === language) {
      return <li>
                <b>
                  {lang} {feature} APIs
                </b>{" "}
                (this page)
              </li>;
    } else {
      return <li>
                <a href={`../${lang.toLowerCase()}/${page}`}>
                  {lang} {feature} APIs
                </a>
              </li>;
    }
  });
})()}
    </ul>
  </Note>;

<SdkHeader language="AssemblyScript" feature="Console" />

The Modus Console APIs allow you to capture information from your functions,
such as errors and other information that can help you debug your functions.

<Info>
  Unlike other APIs, the `console` namespace is globally available by default in
  all AssemblyScript functions, you don't need to import it.
</Info>

The Console APIs mimic the behavior of the AssemblyScript
[`console`](https://www.assemblyscript.org/stdlib/console.html) object, but
directs the output to Hypermode as follows:

* All console output is available in the runtime logs. When hosting on
  Hypermode, the logs are available in the "Function Runs" section of the
  Console UI.
* Output from `console.error` is also sent to the GraphQL response.
* Errors thrown with the `throw` keyword are also sent to the GraphQL response.

## Console APIs

{/* vale Google.Headings = NO */}

The APIs in the `console` namespace are below, organized by category.

<Tip>
  We're constantly introducing new APIs through ongoing development with early
  users. Please [open an issue](https://github.com/hypermodeinc/modus/issues) if
  you have ideas on what would make Modus even more powerful for your next app!
</Tip>

### Assertion Functions

#### assert

Asserts that a condition is true, and logs an error if it's not.

```ts
function assert<T>(assertion: T, message?: string): void
```

<ResponseField name="assertion" required>
  The condition to assert. Typically a boolean value. In the case of an object,
  asserts that the object isn't `null`.
</ResponseField>

<ResponseField name="message" type="string">
  An error message to log, if the assertion is false.
</ResponseField>

### Logging Functions

#### log

Generate a log message, with no particular logging level.

```ts
function log(message?: string): void
```

<ResponseField name="message" type="string">
  A message you want to log.
</ResponseField>

#### debug

Generate a log message with the "debug" logging level.

```ts
function debug(message?: string): void
```

<ResponseField name="message" type="string">
  A debug message you want to log.
</ResponseField>

#### info

Generate a log message with the "info" logging level.

```ts
function info(message?: string): void
```

<ResponseField name="message" type="string">
  An informational message you want to log.
</ResponseField>

#### warn

Generate a log message with the "warning" logging level.

```ts
function warn(message?: string): void
```

<ResponseField name="message" type="string">
  A warning message you want to log.
</ResponseField>

#### error

Generate a log message with the "error" logging level.

```ts
function error(message?: string): void
```

<ResponseField name="message" type="string">
  An error message you want to log.
</ResponseField>

### Timing Functions

#### time

Starts a new timer using the specified label.

```ts
function time(label?: string): void
```

<ResponseField name="label" type="string">
  An optional label for the timer.
</ResponseField>

#### timeLog

Logs the current value of a timer previously started with `console.time`.

```ts
function timeLog(label?: string): void
```

<ResponseField name="label" type="string">
  An optional label for the timer.
</ResponseField>

#### timeEnd

Logs the current value of a timer previously started with `console.time`, and
discards the timer.

```ts
function timeEnd(label?: string): void
```

<ResponseField name="label" type="string">
  An optional label for the timer.
</ResponseField>


# Dgraph APIs
Source: https://docs.hypermode.com/modus/sdk/assemblyscript/dgraph

Execute queries and mutations against a Dgraph database

export const SdkHeader = ({language, feature}) => <Note>
    <p>
      While each Modus SDK offers similar capabilities, the APIs and usage may
      vary between languages.
    </p>
    <p>
      Modus {feature} APIs documentation is available on the following pages:
    </p>
    <ul>
      {(() => {
  const languages = ["AssemblyScript", "Go"];
  const page = feature.toLowerCase().replace(/\W/g, "");
  return languages.map(lang => {
    if (lang === language) {
      return <li>
                <b>
                  {lang} {feature} APIs
                </b>{" "}
                (this page)
              </li>;
    } else {
      return <li>
                <a href={`../${lang.toLowerCase()}/${page}`}>
                  {lang} {feature} APIs
                </a>
              </li>;
    }
  });
})()}
    </ul>
  </Note>;

<SdkHeader language="AssemblyScript" feature="Dgraph" />

The Modus Dgraph APIs allow you to run queries and mutations against a Dgraph
database.

## Import

To begin, import the `dgraph` namespace from the SDK:

```ts
import { dgraph } from "@hypermode/modus-sdk-as"
```

## Dgraph APIs

{/* vale Google.Headings = NO */}

The APIs in the `dgraph` namespace are below, organized by category.

<Tip>
  We're constantly introducing new APIs through ongoing development with early
  users. Please [open an issue](https://github.com/hypermodeinc/modus/issues) if
  you have ideas on what would make Modus even more powerful for your next app!
</Tip>

### Functions

#### alterSchema

Alter the schema of a Dgraph database.

```ts
function alterSchema(connection: string, schema: string): string
```

<ResponseField name="connection" type="string" required>
  Name of the connection, as [defined in the
  manifest](/modus/app-manifest#connections).
</ResponseField>

<ResponseField name="schema" type="string" required>
  The schema to apply to the Dgraph database.
</ResponseField>

#### dropAll

Drop all data from a Dgraph database.

```ts
function dropAll(connection: string): string
```

<ResponseField name="connection" type="string" required>
  Name of the connection, as [defined in the
  manifest](/modus/app-manifest#connections).
</ResponseField>

#### dropAttr

Drop an attribute from a Dgraph schema.

```ts
function dropAttr(connection: string, attr: string): string
```

<ResponseField name="connection" type="string" required>
  Name of the connection, as [defined in the
  manifest](/modus/app-manifest#connections).
</ResponseField>

<ResponseField name="attr" type="string" required>
  The attribute to drop from the Dgraph schema.
</ResponseField>

#### escapeRDF

Ensures proper escaping of RDF string literals.

```ts
function escapeRDF(value: string): string
```

<ResponseField name="value" type="string" required>
  The RDF string literal to escape.
</ResponseField>

#### executeMutations

Execute one or more mutations, without a filtering query.

<Tip>
  If you need to filter the mutations based on a query, use the
  [`executeQuery`](#executequery) function instead, and pass the mutations after
  the query.
</Tip>

```ts
function executeMutations(
  connection: string,
  ...mutations: Mutation[]
): Response
```

<ResponseField name="connection" type="string" required>
  Name of the connection, as [defined in the
  manifest](/modus/app-manifest#connections).
</ResponseField>

<ResponseField name="mutations" type="...Mutation[]" required>
  One or more [`Mutation`](#mutation) objects to execute.
</ResponseField>

#### executeQuery

Execute a DQL query to retrieve data from a Dgraph database.

Also used to execute a filtering query and apply one or more mutations to the
result of the query.

<Tip>
  If you need apply mutations *without* a filtering query, use the
  [`executeMutations`](#executemutations) function instead.
</Tip>

```ts
function executeQuery(
  connection: string,
  query: Query,
  ...mutations: Mutation[]
): Response
```

<ResponseField name="connection" type="string" required>
  Name of the connection, as [defined in the
  manifest](/modus/app-manifest#connections).
</ResponseField>

<ResponseField name="request" type="Query" required>
  A [`Query`](#query) object describing the DQL query to execute.
</ResponseField>

<ResponseField name="mutations" type="...Mutation[]">
  Optional parameters specifying one or more [`Mutation`](#mutation) objects to
  execute on the nodes matched by the query.
</ResponseField>

### Types

#### Mutation

A Dgraph mutation object, used to execute mutations.

```ts
class Mutation {
  setJson: string
  delJson: string
  setNquads: string
  delNquads: string
  condition: string
  withSetJson(json: string): Mutation
  withDelJson(json: string): Mutation
  withSetNquads(nquads: string): Mutation
  withDelNquads(nquads: string): Mutation
  withCondition(cond: string): Mutation
}
```

<ResponseField name="new dgraph.Mutation(setJson, delJson, setNquads, delNquads, condition)">
  Creates a new `Mutation` object with the given `setJson`, `delJson`,
  `setNquads`, `delNquads`, and `condition` fields.
</ResponseField>

<ResponseField name="setJson" type="string">
  A JSON string representing the data to set in the mutation.
</ResponseField>

<ResponseField name="delJson" type="string">
  A JSON string representing the data to delete in the mutation.
</ResponseField>

<ResponseField name="setNquads" type="string">
  A string representing the data to set in the mutation in RDF N-Quads format.
</ResponseField>

<ResponseField name="delNquads" type="string">
  A string representing the data to delete in the mutation in RDF N-Quads
  format.
</ResponseField>

<ResponseField name="condition" type="string">
  A string representing the condition query for the mutation, as a DQL `@if`
  directive.
</ResponseField>

<ResponseField name="withSetJson(json)">
  Sets the `setJson` field of the mutation to the given `json` string. Returns
  the `Mutation` object to allow for method chaining.
</ResponseField>

<ResponseField name="withDelJson(json)">
  Sets the `delJson` field of the mutation to the given `json` string. Returns
  the `Mutation` object to allow for method chaining.
</ResponseField>

<ResponseField name="withSetNquads(nquads)">
  Sets the `setNquads` field of the mutation to the given `nquads` string.
  Returns the `Mutation` object to allow for method chaining.
</ResponseField>

<ResponseField name="withDelNquads(nquads)">
  Sets the `delNquads` field of the mutation to the given `nquads` string.
  Returns the `Mutation` object to allow for method chaining.
</ResponseField>

<ResponseField name="withCondition(cond)">
  Sets the `condition` field of the mutation to the given `cond` string, which
  should be a DQL `@if` directive. Returns the `Mutation` object to allow for
  method chaining.
</ResponseField>

#### Query

A Dgraph query object, used to execute queries.

```ts
class Query {
  query: string = ""
  variables: Map<string, string> = new Map<string, string>()
  withVariable<T>(name: string, value: T): this
}
```

<ResponseField name="new dgraph.Query(query, variables)">
  Creates a new `Query` object with the given `query` and `variables`. `query`
  is a Dgraph Query Language (DQL) query string, and `variables` is an optional
  [`Variables`](#variables) object.
</ResponseField>

<ResponseField name="query" type="string">
  The DQL query to execute.
</ResponseField>

<ResponseField name="variables" type="Map<string, string>">
  A map of query variables, with values encoded as JSON strings.
</ResponseField>

<ResponseField name="withVariable(name, value)">
  Sets a query variable with the given `name` and `value`. `name` is of type
  `string`, and `value` can be a string, number, or boolean.

  Returns the `Query` object to allow for method chaining.

  <Tip>
    The `withVariable` method is the preferred way to set query variables in a
    `Query` object, and allows for fluent method chaining to add multiple variables.
    For example:

    ```ts
    const query = new Query(`
      query all($name: string, $age: int) {
        all(func: eq(name, $name)) {
          name
          age
        }
      }
    `)
      .withVariable("name", "Alice")
      .withVariable("age", 30)

    const response = dgraph.executeQuery("my-dgraph-connection", query)
    ```
  </Tip>
</ResponseField>

#### Request

A Dgraph request object, used to execute queries and mutations.

<Info>
  {/* vale Google.Passive = NO */}

  This object was used by the `execute` function, which has been replaced by the
  [`executeQuery`](#executequery) and [`executeMutations`](#executemutations)
  functions. You should no longer need to create a `Request` object directly.

  {/* vale Google.Passive = YES */}
</Info>

```ts
class Request {
  query: Query = new Query()
  mutations: Mutation[] = []
}
```

<ResponseField name="new dgraph.Request(query, mutations)">
  Creates a new `Request` object with the given `query` and `mutations`.

  The [`query`](#query) and [`mutations`](#mutation) fields are optional and
  default to `null`.
</ResponseField>

<ResponseField name="query" type="Query">
  A Dgraph [`query`](#query) object.
</ResponseField>

<ResponseField name="mutations" type="Mutation[]">
  An array of Dgraph [`mutation`](#mutation) objects.
</ResponseField>

#### Variables

A Variables object used to set query variables in a Dgraph query.

<Info>
  As of SDK version 0.17.1, it's no longer necessary to explicitly create a
  `Variables` object. Instead, use the `withVariable` method on the
  [`Query`](#query) object to set query variables.
</Info>

```ts
class Variables {
  set<T>(name: string, value: T): void
  toMap(): Map<string, string>
}
```

<ResponseField name="Variables.set(name, value)">
  Sets a query variable with the given `name` and `value`. `name` is of type
  `string`, and `value` can be a string, number, or boolean.
</ResponseField>

<ResponseField name="Variables.toMap()">
  Returns a map of all query variables set in the `Variables` object, with
  values encoded as strings.
</ResponseField>


# GraphQL APIs
Source: https://docs.hypermode.com/modus/sdk/assemblyscript/graphql

Access external GraphQL data sources from your functions

export const SdkHeader = ({language, feature}) => <Note>
    <p>
      While each Modus SDK offers similar capabilities, the APIs and usage may
      vary between languages.
    </p>
    <p>
      Modus {feature} APIs documentation is available on the following pages:
    </p>
    <ul>
      {(() => {
  const languages = ["AssemblyScript", "Go"];
  const page = feature.toLowerCase().replace(/\W/g, "");
  return languages.map(lang => {
    if (lang === language) {
      return <li>
                <b>
                  {lang} {feature} APIs
                </b>{" "}
                (this page)
              </li>;
    } else {
      return <li>
                <a href={`../${lang.toLowerCase()}/${page}`}>
                  {lang} {feature} APIs
                </a>
              </li>;
    }
  });
})()}
    </ul>
  </Note>;

<SdkHeader language="AssemblyScript" feature="GraphQL" />

The Modus GraphQL APIs allow you to securely call and fetch data from any
GraphQL endpoint.

## Import

To begin, import the `graphql` namespace from the SDK:

```ts
import { graphql } from "@hypermode/modus-sdk-as"
```

## GraphQL APIs

{/* vale Google.Headings = NO */}

The APIs in the `graphql` namespace are below, organized by category.

<Tip>
  We're constantly introducing new APIs through ongoing development with early
  users. Please [open an issue](https://github.com/hypermodeinc/modus/issues) if
  you have ideas on what would make Modus even more powerful for your next app!
</Tip>

### Functions

#### execute

Execute a GraphQL statement to call a query or apply mutation against a GraphQL
endpoint.

```ts
function execute<T>(
  connection: string,
  statement: string,
  variables?: Variables,
): Response<T>
```

<ResponseField name="T" required>
  Type of object to use for the data returned from the query. This can be any
  type, including a custom type defined in your project. It should match the shape
  of the data returned from the GraphQL query.

  <Tip>
    Define custom types in the project's source code. In AssemblyScript, create
    classes decorated with `@json`.

    All types, including classes, base classes, and field types must be JSON
    serializable. You can also use built-in types such as strings, numbers, arrays,
    and maps.
  </Tip>
</ResponseField>

<ResponseField name="connection" type="string" required>
  Name of the connection, as [defined in the
  manifest](/modus/app-manifest#connection).
</ResponseField>

<ResponseField name="statement" type="string" required>
  GraphQL statement containing the query or mutation operation to execute.

  <Warning>
    While it's possible to directly include parameter values into your GraphQL
    statement, it's highly recommended to pass a [`Variables`](#variables) object
    instead. This can help to prevent against injection attacks and other security
    vulnerabilities.
  </Warning>
</ResponseField>

<ResponseField name="variables" type="Variables">
  Optional variables to include with the query.

  See the details of the [`Variables`](#variables) object for more information.
</ResponseField>

### Types

#### Variables

A container for variables to include with a GraphQL operation.

To use this feature, create a new `Variables` object and call the `set` method
for each variable you want to include. Then pass the object to the `execute`
function.

```ts
class Variables {
  set<T>(name: string, value: T): void
  toJSON(): string
}
```

<ResponseField name="set(name, value)">
  Set a variable with a name and value to include with the GraphQL operation.

  <Expandable title="parameters">
    {/* markdownlint-disable MD046 */}

    <ResponseField name="name" type="string" required>
      The name of the variable to include in the GraphQL operation.
    </ResponseField>

    <ResponseField name="value" required>
      The value of the variable to include in the GraphQL operation.

      The value can be of any type that's JSON serializable, including strings,
      numbers, boolean values, arrays, maps, and custom objects decorated with
      `@json`.
    </ResponseField>

    {/* markdownlint-restore MD046 */}
  </Expandable>
</ResponseField>

<ResponseField name="toJSON()" type="string">
  Serializes the variables to a JSON string for inclusion in the GraphQL
  operation. The `execute` function calls this automatically when you pass a
  `Variables` object. You typically don't need to call it directly.
</ResponseField>

#### Response

A response object from the GraphQL query.

Either `errors` or `data` is present, depending on the result of the query.

```ts
class Response<T> {
  errors: ErrorResult[] | null
  data: T | null
}
```

<ResponseField name="errors" type="ErrorResult[]">
  An array of errors incurred as part of your GraphQL request, if any.

  Each error in the array is an [`ErrorResult`](#errorresult) object. If there are
  no errors, this field is `null`.
</ResponseField>

<ResponseField name="data" type="T">
  The resulting data selected by the GraphQL operation.

  The data has the type specified in the call to the `execute` function. If data
  is absent due to errors, this field is `null`.
</ResponseField>

#### ErrorResult

The details of an error incurred as part of a GraphQL operation.

```ts
class ErrorResult {
  message: string
  locations: CodeLocation[] | null
  path: string[] | null
}
```

<ResponseField name="message" type="string">
  Description of the error incurred.
</ResponseField>

<ResponseField name="locations" type="CodeLocation[]">
  An array of [`CodeLocation`](#codelocation) objects that point to the specific
  location of the error in the GraphQL statement.
</ResponseField>

<ResponseField name="path" type="string[]">
  Path to the area of the GraphQL statement related to the error.

  Each item in the array represents a segment of the path.
</ResponseField>

#### CodeLocation

The location of specific code within a GraphQL statement.

```ts
class CodeLocation {
  line: u32
  column: u32
}
```

<ResponseField name="line" type="u32">
  Line number within the GraphQL statement for the code.
</ResponseField>

<ResponseField name="column" type="u32">
  Column number within the GraphQL statement for the code.
</ResponseField>


# HTTP APIs
Source: https://docs.hypermode.com/modus/sdk/assemblyscript/http

Access external HTTP endpoints from your functions

export const SdkHeader = ({language, feature}) => <Note>
    <p>
      While each Modus SDK offers similar capabilities, the APIs and usage may
      vary between languages.
    </p>
    <p>
      Modus {feature} APIs documentation is available on the following pages:
    </p>
    <ul>
      {(() => {
  const languages = ["AssemblyScript", "Go"];
  const page = feature.toLowerCase().replace(/\W/g, "");
  return languages.map(lang => {
    if (lang === language) {
      return <li>
                <b>
                  {lang} {feature} APIs
                </b>{" "}
                (this page)
              </li>;
    } else {
      return <li>
                <a href={`../${lang.toLowerCase()}/${page}`}>
                  {lang} {feature} APIs
                </a>
              </li>;
    }
  });
})()}
    </ul>
  </Note>;

<SdkHeader language="AssemblyScript" feature="HTTP" />

The Modus HTTP APIs allow you to securely call and fetch data from an HTTP
endpoint. It's similar to the HTTP
[`fetch`](https://developer.mozilla.org/docs/Web/API/Fetch_API) API used in
JavaScript, but with some modifications to work with Modus.

<Warning>
  As a security measure, you can only call HTTP endpoints that you
  [defined in your app's manifest](/modus/app-manifest#connections). Any attempt
  to access an arbitrary URL, for a connection not defined in your app's manifest,
  results in an error.

  Additionally, you should use placeholders for connection secrets in the
  manifest, rather than hardcoding them in your functions. Enter the values for
  each connections' secrets via environment variables or the Hypermode UI. This
  ensures that your secrets are securely stored, aren't committed to your
  repository, and aren't visible or accessible from your functions code.
</Warning>

## Import

To begin, import the `http` namespace from the SDK:

```ts
import { http } from "@hypermode/modus-sdk-as"
```

## HTTP APIs

{/* vale Google.Headings = NO */}

The APIs in the `http` namespace are below, organized by category.

<Tip>
  We're constantly introducing new APIs through ongoing development with early
  users. Please [open an issue](https://github.com/hypermodeinc/modus/issues) if
  you have ideas on what would make Modus even more powerful for your next app!
</Tip>

### Functions

#### fetch

Invoke an HTTP endpoint to retrieve data or trigger external action.

Returns a [`Response`](#response) object with the HTTP response data.

```ts
function fetch(
  requestOrUrl: string | Request,
  options: RequestOptions = new RequestOptions(),
): Response
```

<ResponseField name="requestOrUrl" type="string | Request" required>
  Either a URL `string` or a [`Request`](#request) object, describing the HTTP
  request to make.

  If a `string`, the operation uses the `GET` HTTP method with no headers other
  than those defined in the manifest entry of the connection.

  <Note>
    Each request must match to a connection entry in the manifest, using the
    `baseUrl` field. The request URL passed to the `fetch` function (or via a
    `Request` object) must start with the manifest entry's `baseUrl` value to
    match.
  </Note>
</ResponseField>

<ResponseField name="options" type="RequestOptions">
  A [`RequestOptions`](#requestoptions) object with additional options for the
  request, such as the HTTP method, headers, and body.
</ResponseField>

### Types

#### Content

Represents content used in the body of an HTTP request or response.

```ts
class Content {
  static from<T>(value: T): Content
  readonly data: ArrayBuffer
  bytes(): Uint8Array
  text(): string
  json<T>(): T
}
```

<ResponseField name="Content.from(value)">
  Creates a new `Content` object from the given value.

  The value can be of any type that's JSON serializable, including strings,
  numbers, boolean values, arrays, maps, and custom objects decorated with
  `@json`.

  If the value is a `string`, an `ArrayBuffer`, or a `Uint8Array` it's sent as-is,
  without JSON serialization.
</ResponseField>

<ResponseField name="data" type="ArrayBuffer">
  The raw binary content data buffer.
</ResponseField>

<ResponseField name="bytes()">
  Returns the binary content data as a `Uint8Array`.
</ResponseField>

<ResponseField name="text()">
  Interprets the content as a UTF-8 encoded string, and returns it as a `string`
  value.
</ResponseField>

<ResponseField name="json<T>()">
  Interprets the content as a UTF-8 encoded string containing JSON in the shape
  of type `T`, and returns it as a value of type `T`.
</ResponseField>

#### Header

Represents an HTTP request or response header.

```ts
class Header {
  name: string
  values: string[]
}
```

<ResponseField name="name" type="string">
  The name of the header.
</ResponseField>

<ResponseField name="values" type="string[]">
  An array of values for the header. Typically a header has a single value, but
  some headers can have multiple values.
</ResponseField>

#### Headers

Represents a collection of HTTP headers.

```ts
class Headers {
  static from(
    value: string[][] | Map<string, string> | Map<string, string[]>,
  ): Headers
  append(name: string, value: string): void
  entries(): string[][]
  get(name: string): string | null
}
```

<ResponseField name="Headers.from(value)">
  Creates a new `Headers` object from the given `value`.

  The `value` must be one of the following types:

  * A `string[][]`, where each inner array contains a header name and value.
  * A `Map<string, string>`, where the keys are header names and the values are
    header values.
  * A `Map<string, string[]>`, where the keys are header names and the values are
    arrays of header values.
</ResponseField>

<ResponseField name="append(name, value)">
  Appends a new header with the given `name` and `value` to the collection.
</ResponseField>

<ResponseField name="entries()">
  Returns a `string[][]`, where each inner array contains a header name and
  value.
</ResponseField>

<ResponseField name="get(name)">
  Returns the value of the header with the given `name`, or `null` if the header
  doesn't exist. If there are multiple values for the header, this function
  concatenates them with a comma to form a single string.
</ResponseField>

#### Request

Represents an HTTP request to make.

```ts
class Request {
  constructor(url: string, options?: RequestOptions)
  static clone(request: Request, options: RequestOptions): Request
  readonly url: string
  readonly method: string
  readonly headers: Headers
  readonly body: ArrayBuffer
  bytes(): Uint8Array
  text(): string
  json<T>(): T
}
```

<ResponseField name="new http.Request(url, options?)">
  Creates a new `Request` object with the given `url` and `options`.

  The required `url` parameter must be a fully qualified URL of the request,
  including the protocol. For example, `"https://example.com"`.

  The optional `options` parameter is a [`RequestOptions`](#requestoptions) object
  that's used to set the HTTP method, headers, and body if needed.
</ResponseField>

<ResponseField name="Request.clone(request, options)">
  Creates a new `Request` object by cloning the given `request` and applying the
  `options` to it.
</ResponseField>

<ResponseField name="url" type="string">
  The fully qualified URL of the request, including the protocol. For example,
  `"https://example.com"`.
</ResponseField>

<ResponseField name="method" type="string">
  The HTTP method of the request. For example, `"GET"`, `"POST"`, `"PUT"`, or
  `"DELETE"`.
</ResponseField>

<ResponseField name="headers" type="Headers">
  The HTTP headers of the request, as a [`Headers`](#headers) object.
</ResponseField>

<ResponseField name="body" type="ArrayBuffer">
  The raw binary content data buffer of the request body.

  <Tip>
    The request body isn't normally read directly. Instead, use the `bytes`,
    `text` or `json` functions.
  </Tip>
</ResponseField>

<ResponseField name="bytes()">
  Returns the binary content data of the request body as a `Uint8Array`.
</ResponseField>

<ResponseField name="text()">
  Interprets the request body as a UTF-8 encoded string, and returns it as a
  `string` value.
</ResponseField>

<ResponseField name="json<T>()">
  Interprets the request body as a UTF-8 encoded string containing JSON in the
  shape of type `T`, and returns it as a value of type `T`.
</ResponseField>

#### RequestOptions

Options for the HTTP request.

```ts
class RequestOptions {
  method: string | null
  headers: Headers
  body: Content | null
}
```

<ResponseField name="method" type="string | null">
  The HTTP method of the request. For example, `"GET"`, `"POST"`, `"PUT"`, or
  `"DELETE"`. If `null` (the default), the request uses the `GET` method.
</ResponseField>

<ResponseField name="headers" type="Headers">
  The HTTP headers of the request, as a [`Headers`](#headers) object.

  <Tip>
    By default, the `RequestOptions` contains an empty `Headers` object which you
    can add headers to using the `append` method.
  </Tip>
</ResponseField>

<ResponseField name="body" type="Content | null">
  Content to pass in the request body, as a [`Content`](#content) object, or
  `null` (the default) if there is no body to pass.

  <Tip>
    It's generally recommended to supply a `Content-Type` header for any requests
    that have a body.
  </Tip>
</ResponseField>

#### Response

Represents the response received from the HTTP server.

```ts
class Response {
  readonly status: u16
  readonly statusText: string
  readonly headers: Headers
  readonly body: ArrayBuffer
  readonly ok: bool
  bytes(): Uint8Array
  text(): string
  json<T>(): T
}
```

<ResponseField name="status" type="u16">
  The HTTP response status code, such as `200` for success.
</ResponseField>

<ResponseField name="statusText" type="string">
  The HTTP response status text associated with the status code, such as `"OK"`
  for success.
</ResponseField>

<ResponseField name="headers" type="Headers">
  The HTTP headers received with the response, as a [`Headers`](#headers)
  object.
</ResponseField>

<ResponseField name="body" type="ArrayBuffer">
  The raw binary content data buffer of the response body.

  <Tip>
    The response body isn't normally read directly. Instead, use the `bytes`,
    `text` or `json` functions.
  </Tip>
</ResponseField>

<ResponseField name="ok" type="bool">
  A boolean value indicating whether the response was successful. It's `true` if
  the status code is in the range `200-299`, and `false` otherwise.
</ResponseField>

<ResponseField name="bytes()">
  Returns the binary content data of the response body as a `Uint8Array`.
</ResponseField>

<ResponseField name="text()">
  Interprets the response body content as a UTF-8 encoded string, and returns it
  as a `string` value.
</ResponseField>

<ResponseField name="json<T>()">
  Interprets the response body content as a UTF-8 encoded string containing JSON
  in the shape of type `T`, and returns it as a value of type `T`.
</ResponseField>


# Local Time APIs
Source: https://docs.hypermode.com/modus/sdk/assemblyscript/localtime

Access the user's local time and time zone in your functions

export const SdkHeader = ({language, feature}) => <Note>
    <p>
      While each Modus SDK offers similar capabilities, the APIs and usage may
      vary between languages.
    </p>
    <p>
      Modus {feature} APIs documentation is available on the following pages:
    </p>
    <ul>
      {(() => {
  const languages = ["AssemblyScript", "Go"];
  const page = feature.toLowerCase().replace(/\W/g, "");
  return languages.map(lang => {
    if (lang === language) {
      return <li>
                <b>
                  {lang} {feature} APIs
                </b>{" "}
                (this page)
              </li>;
    } else {
      return <li>
                <a href={`../${lang.toLowerCase()}/${page}`}>
                  {lang} {feature} APIs
                </a>
              </li>;
    }
  });
})()}
    </ul>
  </Note>;

<SdkHeader language="AssemblyScript" feature="Local Time" />

The Modus Local Time APIs allow you to access the user's local time and time
zone from your functions.

## Import

To begin, import the `localtime` namespace from the SDK:

```ts
import { localtime } from "@hypermode/modus-sdk-as"
```

{/* vale Google.Headings = NO */}

## Local Time APIs

The APIs in the `localtime` namespace are below.

All time zones use the IANA time zone database format. For example,
`"America/New_York"`. You can find a list of valid time zones
[here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).

<Info>
  {/* vale Google.Passive = NO */}

  For APIs that work with the user's local time, the time zone is determined in
  the following order of precedence:

  * If the `X-Time-Zone` header is present in the request, the time zone is set to
    the value of the header.
  * If the `TZ` environment variable is set on the host, the time zone is set to
    the value of the variable.
  * Otherwise, the time zone is set to the host's local time zone.

  {/* vale Google.Passive = YES */}
</Info>

<Tip>
  When working locally with `modus dev`, Modus uses the host's local time zone by
  default. You can override this by setting the `TZ` environment variable in your
  `.env.local` file.
</Tip>

<Tip>
  In a browser-based web app, you can get the user's time zone with the following
  JavaScript code:

  ```js
  const timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone
  ```

  Assign that value to a `"X-Time-Zone"` request header when calling Modus, to use
  it for all local time calculations.
</Tip>

<Tip>
  If you just need the current UTC time, you can use AssemblyScript's built-in
  support:

  ```ts
  const now = new Date(Date.now())

  // if you need a string
  const utcTime = now.toISOString()
  ```
</Tip>

<Tip>
  We're constantly introducing new APIs through ongoing development with early
  users. Please [open an issue](https://github.com/hypermodeinc/modus/issues) if
  you have ideas on what would make Modus even more powerful for your next app!
</Tip>

### Functions

#### getTimeZone

Returns the user's time zone in IANA format.

```ts
function getTimeZone(): string
```

#### isValidTimeZone

Determines whether the specified time zone is a valid IANA time zone and
recognized by the system as such.

```ts
function isValidTimeZone(tz: string): bool
```

<ResponseField name="tz" type="string" required>
  An IANA time zone identifier, such as `"America/New_York"`.
</ResponseField>

#### now

Returns the current local time in the user's time zone, as a string in ISO 8601
extended format, including the applicable time zone offset.

For example, `"2025-12-31T12:34:56.789-04:00"`.

```ts
function now(): string
```

#### nowInZone

Returns the current local time in a specified time zone, as a string in ISO 8601
extended format, including the applicable time zone offset.

For example, `"2025-12-31T12:34:56.789-04:00"`.

```ts
function nowInZone(tz: string): string
```

<ResponseField name="tz" type="string" required>
  An IANA time zone identifier, such as `"America/New_York"`.
</ResponseField>


# AI Model APIs
Source: https://docs.hypermode.com/modus/sdk/assemblyscript/models

Invoke AI models from your functions

export const SdkHeader = ({language, feature}) => <Note>
    <p>
      While each Modus SDK offers similar capabilities, the APIs and usage may
      vary between languages.
    </p>
    <p>
      Modus {feature} APIs documentation is available on the following pages:
    </p>
    <ul>
      {(() => {
  const languages = ["AssemblyScript", "Go"];
  const page = feature.toLowerCase().replace(/\W/g, "");
  return languages.map(lang => {
    if (lang === language) {
      return <li>
                <b>
                  {lang} {feature} APIs
                </b>{" "}
                (this page)
              </li>;
    } else {
      return <li>
                <a href={`../${lang.toLowerCase()}/${page}`}>
                  {lang} {feature} APIs
                </a>
              </li>;
    }
  });
})()}
    </ul>
  </Note>;

<SdkHeader language="AssemblyScript" feature="Models" />

The Modus Models APIs allow you to invoke AI models directly from your
functions, irrespective of the model's host.

Since many models have unique interfaces, the design of the Models APIs are
extremely flexible. A common base class forms the core of the APIs, which
extends to conform to any model's required schema.

The SDK contains both the base types and pre-defined implementations for many
commonly used models. You can either use one of the pre-defined model types, or
can create custom types for any model you like, by following the same pattern as
implemented in the pre-defined models.

<Tip>
  For your reference, several complete examples for using the Models APIs are available in
  [Model Invoking](/modus/model-invoking).

  Each example demonstrates using different types of AI models for different
  purposes. However, the Models interface isn't limited to these purposes. You can
  use it for any task that an AI model can perform.
</Tip>

## Import

To begin, import the `models` namespace from the SDK:

```ts
import { models } from "@hypermode/modus-sdk-as"
```

You'll also need to import one or more classes for the model you are working
with. For example:

```ts
import { OpenAIChatModel } from "@hypermode/modus-sdk-as/models/openai"
```

If you would like to request a new model, please
[open an issue](https://github.com/hypermodeinc/modus/issues). You can also send
a pull request, if you'd like to contribute a new model yourself.

## Models APIs

{/* vale Google.Headings = NO */}

The APIs in the `models` namespace are below, organized by category.

<Tip>
  We're constantly introducing new APIs through ongoing development with early
  users. Please [open an issue](https://github.com/hypermodeinc/modus/issues) if
  you have ideas on what would make Modus even more powerful for your next app!
</Tip>

### Functions

#### getModel

Get a model instance by name and type.

```ts
function getModel<T>(modelName: string): T
```

<ResponseField name="T" required>
  The type of model to return. This can be any class that extends the `Model`
  base class.
</ResponseField>

<ResponseField name="modelName" type="string" required>
  The name of the model to retrieve. This must match the name of a model defined
  in your project's manifest file.
</ResponseField>

### Types

#### Model

The base class for all models that Modus functions can invoke.

<Tip>
  If you are implementing a custom model, you should extend this class. You'll
  also need classes to represent the input and output types for your model. See
  the implementations of the pre-defined models in the Modus GitHub repository
  for examples.
</Tip>

```ts
abstract class Model<TInput, TOutput> {
  debug: bool
  info: ModelInfo
  invoke(input: TInput): TOutput
}
```

<ResponseField name="TInput" required>
  The type of the input data for the model. This can be any type, including a
  custom type defined in your project. It should match the shape of the data
  expected by the model. It's usually a class.
</ResponseField>

<ResponseField name="TOutput" required>
  The type of the output data from the model. This can be any type, including a
  custom type defined in your project. It should match the shape of the data
  returned by the model. It's usually a class.
</ResponseField>

<ResponseField name="debug" type="bool">
  A flag to enable debug mode for the model. When enabled, Modus automatically
  logs the full request and response data to the console. Implementations can
  also use this flag to enable additional debug logging. Defaults to `false`.
</ResponseField>

<ResponseField name="info" type="ModelInfo">
  Information about the model set by the Modus Runtime when creating the
  instance. See the [`ModelInfo`](#modelinfo) object for more information.
</ResponseField>

<ResponseField name="invoke(input)" type="method">
  Invokes the model with input data and returns the output data.
</ResponseField>

#### ModelInfo

Information about a model that's used to construct a `Model` instance. It's also
available as a property on the `Model` class.

<Info>
  This class relays information from the Modus runtime to the model
  implementation. Generally, you don't need to create `ModelInfo` instances
  directly.

  However, if you are implementing a custom model, you may wish to use a property
  from this class, such as `fullName`, for model providers that require the model
  name in the input request body.
</Info>

```ts
class ModelInfo {
  readonly name: string
  readonly fullName: string
}
```

<ResponseField name="name" type="string">
  The name of the model from the app manifest.
</ResponseField>

<ResponseField name="fullName" type="string">
  The full name or identifier of the model, as defined by the model provider.
</ResponseField>


# MySQL APIs
Source: https://docs.hypermode.com/modus/sdk/assemblyscript/mysql

Execute queries against a MySQL database

export const SdkHeader = ({language, feature}) => <Note>
    <p>
      While each Modus SDK offers similar capabilities, the APIs and usage may
      vary between languages.
    </p>
    <p>
      Modus {feature} APIs documentation is available on the following pages:
    </p>
    <ul>
      {(() => {
  const languages = ["AssemblyScript", "Go"];
  const page = feature.toLowerCase().replace(/\W/g, "");
  return languages.map(lang => {
    if (lang === language) {
      return <li>
                <b>
                  {lang} {feature} APIs
                </b>{" "}
                (this page)
              </li>;
    } else {
      return <li>
                <a href={`../${lang.toLowerCase()}/${page}`}>
                  {lang} {feature} APIs
                </a>
              </li>;
    }
  });
})()}
    </ul>
  </Note>;

<SdkHeader language="AssemblyScript" feature="MySQL" />

The Modus MySQL APIs allow you to run queries against MySQL or any
MySQL-compatible database platform.

## Import

To begin, import the `mysql` namespace from the SDK:

```ts
import { mysql } from "@hypermode/modus-sdk-as"
```

## MySQL APIs

{/* vale Google.Headings = NO */}

The APIs in the `mysql` namespace are below, organized by category.

<Tip>
  We're constantly introducing new APIs through ongoing development with early
  users. Please [open an issue](https://github.com/hypermodeinc/modus/issues) if
  you have ideas on what would make Modus even more powerful for your next app!
</Tip>

### Functions

#### execute

Execute a SQL statement against a MySQL database, without any data returned. Use
this for insert, update, or delete operations, or for other SQL statements that
don't return data.

<Note>
  The `execute` function is for operations that don't return data. However, some
  insert/update/delete operations may still return data. In these cases, you can
  use the `queryScalar` or `query` functions instead.
</Note>

```ts
function execute(
  connection: string,
  statement: string,
  params?: Params,
): Response
```

<ResponseField name="connection" type="string" required>
  Name of the connection, as [defined in the
  manifest](/modus/app-manifest#connections).
</ResponseField>

<ResponseField name="statement" type="string" required>
  SQL statement containing the query or mutation operation to execute.

  <Warning>
    While it's possible to directly include parameter values into your SQL
    statement, it's highly recommended to pass a [`Params`](#params) object
    instead. This can help to protect against injection attacks and other security
    vulnerabilities.
  </Warning>
</ResponseField>

<ResponseField name="params" type="Params">
  Optional parameters to include with the query.

  See the details of the [`Params`](#params) object for more information.
</ResponseField>

#### query

Execute a SQL statement against a MySQL database, returning a set of rows. In
the results, each row converts to an object of type `T`, with fields matching
the column names.

```ts
function query<T>(
  connection: string,
  statement: string,
  params?: Params,
): QueryResponse<T>
```

<ResponseField name="T" required>
  Type of object to use for the data returned from the query. This can be any
  type, including a custom type defined in your project. It should match the shape
  of the row returned from the SQL query.

  <Tip>
    Define custom types in the app's source code. In AssemblyScript, create classes
    decorated with `@json`.

    All types, including classes, base classes, and field types must be JSON
    serializable. You can also use built-in types such as strings, numbers, arrays,
    and maps.

    If working with MySQL's `point` data type, you can use a [`Point`](#point) or
    [`Location`](#location) object to represent the data.
  </Tip>
</ResponseField>

<ResponseField name="connection" type="string" required>
  Name of the connection, as [defined in the
  manifest](/modus/app-manifest#connections).
</ResponseField>

<ResponseField name="statement" type="string" required>
  SQL statement containing the query or mutation operation to execute.

  <Warning>
    While it's possible to directly include parameter values into your SQL
    statement, it's highly recommended to pass a [`Params`](#params) object
    instead. This can help to protect against injection attacks and other security
    vulnerabilities.
  </Warning>
</ResponseField>

<ResponseField name="params" type="Params">
  Optional parameters to include with the query.

  See the details of the [`Params`](#params) object for more information.
</ResponseField>

#### queryScalar

Execute a SQL statement against a MySQL database, returning a single scalar
value. For example, the result could be a count, sum, or average, or it could be
an identifier.

```ts
function queryScalar<T>(
  connection: string,
  statement: string,
  params?: Params,
): ScalarResponse<T>
```

<ResponseField name="T" required>
  Type of object to use for the data returned from the query. This should
  generally be a scalar data type, such as a number or string. It should match
  the type of the data returned from the SQL query.
</ResponseField>

<ResponseField name="connection" type="string" required>
  Name of the connection, as [defined in the
  manifest](/modus/app-manifest#connections).
</ResponseField>

<ResponseField name="statement" type="string" required>
  SQL statement containing the query or mutation operation to execute.

  <Warning>
    While it's possible to directly include parameter values into your SQL
    statement, it's highly recommended to pass a [`Params`](#params) object
    instead. This can help to protect against injection attacks and other security
    vulnerabilities.
  </Warning>
</ResponseField>

<ResponseField name="params" type="Params">
  Optional parameters to include with the query.

  See the details of the [`Params`](#params) object for more information.
</ResponseField>

### Types

#### Location

Represents a location on Earth, having `longitude` and `latitude` coordinates.

Correctly serializes to and from MySQL's point type, in (longitude, latitude)
order.

<Info>
  This class is identical to the [Point](#point) class, but uses different field
  names.
</Info>

```ts
class Location {
 longitude: f64,
 latitude: f64,
}
```

<ResponseField name="longitude" type="f64" required>
  The longitude coordinate of the location, in degrees.
</ResponseField>

<ResponseField name="latitude" type="f64" required>
  The latitude coordinate of the location, in degrees.
</ResponseField>

#### Params

A container for parameters to include with a SQL operation.

To use this feature, create a new `Params` object and call the `push` method for
each parameter you want to include. Then pass the object to the `execute`,
`query`, or `queryScalar` function along with your SQL statement.

```ts
class Params {
  push<T>(value: T): void
  toJSON(): string
}
```

<ResponseField name="push(value)">
  Push a parameter value into the list included with the SQL operation. The
  sequence of calls to `push` determines the order of the parameters in the SQL
  statement. This corresponds to the order of the `?` placeholders or `$1`, `$2`,
  etc.

  <Expandable title="parameters">
    {/* markdownlint-disable MD046 */}

    <ResponseField name="value" required>
      The value of the parameter to include in the SQL operation.

      The value can be of any type that's JSON serializable, including strings,
      numbers, boolean values, arrays, maps, and custom objects decorated with
      `@json`, as long as the database supports it.

      <Tip>
        If working with MySQL's `Point` data type, you can either pass separate
        parameters for the coordinates and use a `point()` function in the SQL
        statement, or you can pass a [`Point`](#point) or [`Location`](#location)
        object as a single parameter.
      </Tip>
    </ResponseField>

    {/* markdownlint-restore MD046 */}
  </Expandable>
</ResponseField>

<ResponseField name="toJSON()" type="string">
  Serializes the parameters to a JSON string for inclusion in the SQL operation.
  The SDK functions call this automatically when you pass a `Params` object. You
  typically don't need to call it directly.
</ResponseField>

#### Point

Represents a point in 2D space, having `x` and `y` coordinates. Correctly
serializes to and from MySQL's point type, in (x, y) order.

<Info>
  This class is identical to the [Location](#location) class, but uses different
  field names.
</Info>

```ts
class Point {
 x: f64,
 y: f64,
}
```

<ResponseField name="x" type="f64" required>
  The x coordinate of the point.
</ResponseField>

<ResponseField name="y" type="f64" required>
  The y coordinate of the point.
</ResponseField>

#### QueryResponse

Represents the response from a [`query`](#query) operation.

```ts
class QueryResponse<T> {
  error: string | null
  rowsAffected: u32
  lastInsertId: u64
  rows: T[]
}
```

<ResponseField name="error" type="string | null">
  An error message, if an error occurred during the operation. Otherwise, this
  field is `null`.
</ResponseField>

<ResponseField name="rowsAffected" type="u32">
  The number of rows affected by the operation, which typically corresponds to
  the number of rows returned.
</ResponseField>

<ResponseField name="lastInsertId" type="u64">
  When inserting a row, this field contains the ID of the last inserted row.
  This is useful for tables with auto-incrementing primary keys.
</ResponseField>

<ResponseField name="rows" type="T[]">
  An array of objects, each representing a row returned from the query. Each
  object has fields corresponding to the columns in the result set.
</ResponseField>

#### Response

Represents the response from an [`execute`](#execute) operation. Also serves as
the base class for `QueryResponse<T>` and `ScalarResponse<T>`.

```ts
class Response {
  error: string | null
  rowsAffected: u32
  lastInsertId: u64
}
```

<ResponseField name="error" type="string | null">
  An error message, if an error occurred during the operation. Otherwise, this
  field is `null`.
</ResponseField>

<ResponseField name="rowsAffected" type="u32">
  The number of rows affected by the operation.
</ResponseField>

<ResponseField name="lastInsertId" type="u64">
  When inserting a row, this field contains the ID of the last inserted row.
  This is useful for tables with auto-incrementing primary keys.
</ResponseField>

#### ScalarResponse

Represents the response from a [`queryScalar`](#queryscalar) operation.

```ts
class ScalarResponse<T> {
  error: string | null
  rowsAffected: u32
  lastInsertId: u64
  value: T
}
```

<ResponseField name="error" type="string | null">
  An error message, if an error occurred during the operation. Otherwise, this
  field is `null`.
</ResponseField>

<ResponseField name="rowsAffected" type="u32">
  The number of rows affected by the operation, which is typically 1 for a
  scalar query.
</ResponseField>

<ResponseField name="lastInsertId" type="u64">
  When inserting a row, this field contains the ID of the last inserted row.
  This is useful for tables with auto-incrementing primary keys.
</ResponseField>

<ResponseField name="value" type="T">
  The scalar value returned from the query.
</ResponseField>


# Neo4j APIs
Source: https://docs.hypermode.com/modus/sdk/assemblyscript/neo4j

Execute queries and mutations against a Neo4j database

export const SdkHeader = ({language, feature}) => <Note>
    <p>
      While each Modus SDK offers similar capabilities, the APIs and usage may
      vary between languages.
    </p>
    <p>
      Modus {feature} APIs documentation is available on the following pages:
    </p>
    <ul>
      {(() => {
  const languages = ["AssemblyScript", "Go"];
  const page = feature.toLowerCase().replace(/\W/g, "");
  return languages.map(lang => {
    if (lang === language) {
      return <li>
                <b>
                  {lang} {feature} APIs
                </b>{" "}
                (this page)
              </li>;
    } else {
      return <li>
                <a href={`../${lang.toLowerCase()}/${page}`}>
                  {lang} {feature} APIs
                </a>
              </li>;
    }
  });
})()}
    </ul>
  </Note>;

<SdkHeader language="AssemblyScript" feature="Neo4j" />

The Modus Neo4j APIs allow you to run queries and mutations against a Neo4j
database.

## Import

To begin, import the `neo4j` namespace from the SDK:

```ts
import { neo4j } from "@hypermode/modus-sdk-as"
```

## Neo4j APIs

{/* vale Google.Headings = NO */}

The APIs in the `neo4j` namespace are below, organized by category.

<Tip>
  We're constantly introducing new APIs through ongoing development with early
  users. Please [open an issue](https://github.com/hypermodeinc/modus/issues) if
  you have ideas on what would make Modus even more powerful for your next app!
</Tip>

### Functions

#### executeQuery

Executes a Cypher query on the Neo4j database.

```ts
function executeQuery(
  connection: string,
  query: string,
  parameters: Variables = new Variables(),
  dbName: string = "neo4j",
): EagerResult
```

<ResponseField name="connection" type="string" required>
  Name of the connection, as [defined in the
  manifest](/modus/app-manifest#connections).
</ResponseField>

<ResponseField name="query" type="string" required>
  A Neo4j Cypher query to execute.
</ResponseField>

<ResponseField name="parameters" type="Variables">
  The parameters to pass to the query.
</ResponseField>

<ResponseField name="dbName" type="string">
  An optional database name to use. Defaults to "neo4j" if not provided.
</ResponseField>

### Types

#### EagerResult

The result of a Neo4j query.

```ts
class EagerResult {
  Keys: string[]
  Records: Record[]
}
```

<ResponseField name="keys" type="string[]">
  The keys of the result.
</ResponseField>

<ResponseField name="records" type="Record[]">
  The records of the result.
</ResponseField>

#### Entity

An abstract class representing possible entities in a Neo4j query result.

```ts
abstract class Entity {
  elementId: string
  props: DynamicMap
}
```

<ResponseField name="elementId" type="string">
  The ID of the entity.
</ResponseField>

<ResponseField name="props" type="DynamicMap">
  The properties of the entity.
</ResponseField>

#### Node

A node in a Neo4j query result.

```ts
class Node extends Entity {
  elementId: string // from base class
  props: DynamicMap // from base class
  labels: string[]
}
```

<ResponseField name="elementId" type="string">
  The ID of the node.
</ResponseField>

<ResponseField name="props" type="DynamicMap">
  The properties of the node.
</ResponseField>

<ResponseField name="labels" type="string[]">
  The labels of the node.
</ResponseField>

#### Path

A path in a Neo4j query result.

```ts
class Path {
  nodes: Node[]
  relationships: Relationship[]
}
```

<ResponseField name="nodes" type="Node[]">
  The nodes in the path.
</ResponseField>

<ResponseField name="relationships" type="Relationship[]">
  The relationships in the path.
</ResponseField>

#### Point2D

A 2D point in a Neo4j query result.

```ts
class Point2D {
  x: f64
  y: f64
  spatialRefId: u32
}
```

<ResponseField name="x" type="f64">
  The X coordinate of the point.
</ResponseField>

<ResponseField name="y" type="f64">
  The Y coordinate of the point.
</ResponseField>

<ResponseField name="spatialRefId" type="u32">
  The spatial reference ID of the point.
</ResponseField>

#### Point3D

A 3D point in a Neo4j query result.

```ts
class Point3D {
  x: f64
  y: f64
  z: f64
  spatialRefId: u32
}
```

<ResponseField name="x" type="f64">
  The X coordinate of the point.
</ResponseField>

<ResponseField name="y" type="f64">
  The Y coordinate of the point.
</ResponseField>

<ResponseField name="z" type="f64">
  The Z coordinate of the point.
</ResponseField>

<ResponseField name="spatialRefId" type="u32">
  The spatial reference ID of the point.
</ResponseField>

#### Record

A record in a Neo4j query result.

```ts
class Record {
  keys: string[]
  values: string[]
  get(key: string): string
  getValue<T>(key: string): T
  asMap(): Map<string, string>
}
```

<ResponseField name="keys" type="string[]">
  The keys of the record.
</ResponseField>

<ResponseField name="values" type="string[]">
  The values of the record.
</ResponseField>

<ResponseField name="get(key)" type="method">
  Get a value from a record at a given key as a JSON encoded string.

  <Info>
    Usually, you should use `getValue<T>(key)` instead of this method.
  </Info>
</ResponseField>

<ResponseField name="getValue<T>(key)" type="method">
  Get a value from a record at a given key and cast or decode it to a specific
  type.
</ResponseField>

<ResponseField name="asMap()" type="method">
  Convert the record to a map of keys and JSON encoded string values.
</ResponseField>

#### Relationship

A relationship in a Neo4j query result.

```ts
class Relationship extends Entity {
  elementId: string // from base class
  props: DynamicMap // from base class
  startElementId: string
  endElementId: string
  type: string
}
```

<ResponseField name="elementId" type="string">
  The ID of the relationship.
</ResponseField>

<ResponseField name="props" type="DynamicMap">
  The properties of the relationship.
</ResponseField>

<ResponseField name="startElementId" type="string">
  The ID of the start node.
</ResponseField>

<ResponseField name="endElementId" type="string">
  The ID of the end node.
</ResponseField>

<ResponseField name="type" type="string">
  The type of the relationship.
</ResponseField>


# Modus AssemblyScript SDK
Source: https://docs.hypermode.com/modus/sdk/assemblyscript/overview

Learn how to use the Modus AssemblyScript SDK

export const language_0 = "AssemblyScript"

The Modus {language_0} SDK provides a set of APIs that allow you to interact with
various databases and services in Modus apps written in {language_0}. It's
designed to work seamlessly with the Modus platform, enabling you to build
powerful applications with ease.

<Info>
  The Modus SDKs come in multiple languages, each following the conventions for
  that language, including its capabilities and limitations. While each SDK
  provides similar features, the APIs may differ slightly between languages. Be
  sure to refer to the documentation for the specific SDK you're using.

  Wherever possible, we've tried to keep the APIs consistent across languages.
  However, you may find differences in the APIs due to language-specific
  constraints.

  If you have any questions or need help, please reach out to us via the `#modus`
  channel on the [Hypermode Discord server](https://discord.hypermode.com/).
</Info>

## Importing the APIs

The Modus AssemblyScript SDK organizes its APIs into namespaces based on their
purpose. In your AssemblyScript code, you can import each namespace you'd like
to use like this:

```ts
import { <namespace> } from "@hypermode/modus-sdk-as"
```

## Available APIs

<Tip>
  We're constantly introducing new APIs through ongoing development with early
  users. Please [open an issue](https://github.com/hypermodeinc/modus/issues) if
  you have ideas on what would make Modus even more powerful for your next app!
</Tip>

The following namespaces are available. They're grouped into categories below
for your convenience. Click on a namespace to view more information about its
APIs.

### Client APIs

| Namespace              | Purpose                                                                            |
| :--------------------- | :--------------------------------------------------------------------------------- |
| [`http`](./http)       | Provides access to external HTTP endpoints, including REST APIs and other services |
| [`graphql`](./graphql) | Allows you to securely call and fetch data from any GraphQL endpoint               |

### Database APIs

| Namespace                    | Purpose                                         |
| :--------------------------- | :---------------------------------------------- |
| [`dgraph`](./dgraph)         | Access and modify data in a Dgraph database     |
| [`mysql`](./mysql)           | Access and modify data in a MySQL database      |
| [`neo4j`](./neo4j)           | Access and modify data in a Neo4j database      |
| [`postgresql`](./postgresql) | Access and modify data in a PostgreSQL database |

### Inference APIs

| Namespace            | Purpose                                                                                        |
| :------------------- | :--------------------------------------------------------------------------------------------- |
| [`models`](./models) | Invoke AI models, including large language models, embedding models, and classification models |

### Storage APIs

| Namespace                      | Purpose                                                    |
| :----------------------------- | :--------------------------------------------------------- |
| [`collections`](./collections) | Provides integrated storage and vector search capabilities |

### System APIs

| Namespace                  | Purpose                                                  |
| :------------------------- | :------------------------------------------------------- |
| [`console`](./console)     | Provides logging, assertion, and timing functions        |
| [`localtime`](./localtime) | Allows you to access the user's local time and time zone |


# PostgreSQL APIs
Source: https://docs.hypermode.com/modus/sdk/assemblyscript/postgresql

Execute queries against a PostgreSQL database

export const SdkHeader = ({language, feature}) => <Note>
    <p>
      While each Modus SDK offers similar capabilities, the APIs and usage may
      vary between languages.
    </p>
    <p>
      Modus {feature} APIs documentation is available on the following pages:
    </p>
    <ul>
      {(() => {
  const languages = ["AssemblyScript", "Go"];
  const page = feature.toLowerCase().replace(/\W/g, "");
  return languages.map(lang => {
    if (lang === language) {
      return <li>
                <b>
                  {lang} {feature} APIs
                </b>{" "}
                (this page)
              </li>;
    } else {
      return <li>
                <a href={`../${lang.toLowerCase()}/${page}`}>
                  {lang} {feature} APIs
                </a>
              </li>;
    }
  });
})()}
    </ul>
  </Note>;

<SdkHeader language="AssemblyScript" feature="PostgreSQL" />

The Modus PostgreSQL APIs allow you to run queries against PostgreSQL or any
PostgreSQL-compatible database platform.

## Import

To begin, import the `postgresql` namespace from the SDK:

```ts
import { postgresql } from "@hypermode/modus-sdk-as"
```

## PostgreSQL APIs

{/* vale Google.Headings = NO */}

The APIs in the `postgresql` namespace are below, organized by category.

<Tip>
  We're constantly introducing new APIs through ongoing development with early
  users. Please [open an issue](https://github.com/hypermodeinc/modus/issues) if
  you have ideas on what would make Modus even more powerful for your next app!
</Tip>

### Functions

#### execute

Execute a SQL statement against a PostgreSQL database, without any data
returned. Use this for insert, update, or delete operations, or for other SQL
statements that don't return data.

<Note>
  The `execute` function is for operations that don't return data. However, some
  insert/update/delete operations may still return data. In these cases, you can
  use the `queryScalar` or `query` functions instead.
</Note>

```ts
function execute(
  connection: string,
  statement: string,
  params?: Params,
): Response
```

<ResponseField name="connection" type="string" required>
  Name of the connection, as [defined in the
  manifest](/modus/app-manifest#connections).
</ResponseField>

<ResponseField name="statement" type="string" required>
  SQL statement containing the query or mutation operation to execute.

  <Warning>
    While it's possible to directly include parameter values into your SQL
    statement, it's highly recommended to pass a [`Params`](#params) object
    instead. This can help to protect against injection attacks and other security
    vulnerabilities.
  </Warning>
</ResponseField>

<ResponseField name="params" type="Params">
  Optional parameters to include with the query.

  See the details of the [`Params`](#params) object for more information.
</ResponseField>

#### query

Execute a SQL statement against a PostgreSQL database, returning a set of rows.
In the results, each row converts to an object of type `T`, with fields matching
the column names.

```ts
function query<T>(
  connection: string,
  statement: string,
  params?: Params,
): QueryResponse<T>
```

<ResponseField name="T" required>
  Type of object to use for the data returned from the query. This can be any
  type, including a custom type defined in your project. It should match the shape
  of the row returned from the SQL query.

  <Tip>
    Define custom types in the app's source code. In AssemblyScript, create classes
    decorated with `@json`.

    All types, including classes, base classes, and field types must be JSON
    serializable. You can also use built-in types such as strings, numbers, arrays,
    and maps.

    If working with PostgreSQL's `point` data type, you can use a [`Point`](#point)
    or [`Location`](#location) object to represent the data.
  </Tip>
</ResponseField>

<ResponseField name="connection" type="string" required>
  Name of the connection, as [defined in the
  manifest](/modus/app-manifest#connections).
</ResponseField>

<ResponseField name="statement" type="string" required>
  SQL statement containing the query or mutation operation to execute.

  <Warning>
    While it's possible to directly include parameter values into your SQL
    statement, it's highly recommended to pass a [`Params`](#params) object
    instead. This can help to protect against injection attacks and other security
    vulnerabilities.
  </Warning>
</ResponseField>

<ResponseField name="params" type="Params">
  Optional parameters to include with the query.

  See the details of the [`Params`](#params) object for more information.
</ResponseField>

#### queryScalar

Execute a SQL statement against a PostgreSQL database, returning a single scalar
value. For example, the result could be a count, sum, or average, or it could be
an identifier.

```ts
function queryScalar<T>(
  connection: string,
  statement: string,
  params?: Params,
): ScalarResponse<T>
```

<ResponseField name="T" required>
  Type of object to use for the data returned from the query. This should
  generally be a scalar data type, such as a number or string. It should match
  the type of the data returned from the SQL query.
</ResponseField>

<ResponseField name="connection" type="string" required>
  Name of the connection, as [defined in the
  manifest](/modus/app-manifest#connections).
</ResponseField>

<ResponseField name="statement" type="string" required>
  SQL statement containing the query or mutation operation to execute.

  <Warning>
    While it's possible to directly include parameter values into your SQL
    statement, it's highly recommended to pass a [`Params`](#params) object
    instead. This can help to protect against injection attacks and other security
    vulnerabilities.
  </Warning>
</ResponseField>

<ResponseField name="params" type="Params">
  Optional parameters to include with the query.

  See the details of the [`Params`](#params) object for more information.
</ResponseField>

### Types

#### Location

Represents a location on Earth, having `longitude` and `latitude` coordinates.

Correctly serializes to and from PostgreSQL's point type, in (longitude,
latitude) order.

<Info>
  This class is identical to the [Point](#point) class, but uses different field
  names.
</Info>

```ts
class Location {
 longitude: f64,
 latitude: f64,
}
```

<ResponseField name="longitude" type="f64" required>
  The longitude coordinate of the location, in degrees.
</ResponseField>

<ResponseField name="latitude" type="f64" required>
  The latitude coordinate of the location, in degrees.
</ResponseField>

#### Params

A container for parameters to include with a SQL operation.

To use this feature, create a new `Params` object and call the `push` method for
each parameter you want to include. Then pass the object to the `execute`,
`query`, or `queryScalar` function along with your SQL statement.

```ts
class Params {
  push<T>(value: T): void
  toJSON(): string
}
```

<ResponseField name="push(value)">
  Push a parameter value into the list included with the SQL operation. The
  sequence of calls to `push` determines the order of the parameters in the SQL
  statement. This corresponds to the order of the `?` placeholders or `$1`, `$2`,
  etc.

  <Expandable title="parameters">
    {/* markdownlint-disable MD046 */}

    <ResponseField name="value" required>
      The value of the parameter to include in the SQL operation.

      The value can be of any type that's JSON serializable, including strings,
      numbers, boolean values, arrays, maps, and custom objects decorated with
      `@json`, as long as the database supports it.

      <Tip>
        If working with PostgreSQL's `Point` data type, you can either pass separate
        parameters for the coordinates and use a `point()` function in the SQL
        statement, or you can pass a [`Point`](#point) or [`Location`](#location)
        object as a single parameter.
      </Tip>
    </ResponseField>

    {/* markdownlint-restore MD046 */}
  </Expandable>
</ResponseField>

<ResponseField name="toJSON()" type="string">
  Serializes the parameters to a JSON string for inclusion in the SQL operation.
  The SDK functions call this automatically when you pass a `Params` object. You
  typically don't need to call it directly.
</ResponseField>

#### Point

Represents a point in 2D space, having `x` and `y` coordinates. Correctly
serializes to and from PostgreSQL's point type, in (x, y) order.

<Info>
  This class is identical to the [Location](#location) class, but uses different
  field names.
</Info>

```ts
class Point {
 x: f64,
 y: f64,
}
```

<ResponseField name="x" type="f64" required>
  The x coordinate of the point.
</ResponseField>

<ResponseField name="y" type="f64" required>
  The y coordinate of the point.
</ResponseField>

#### QueryResponse

Represents the response from a [`query`](#query) operation.

```ts
class QueryResponse<T> {
  error: string | null
  rowsAffected: u32
  lastInsertId: u64
  rows: T[]
}
```

<ResponseField name="error" type="string | null">
  An error message, if an error occurred during the operation. Otherwise, this
  field is `null`.
</ResponseField>

<ResponseField name="rowsAffected" type="u32">
  The number of rows affected by the operation, which typically corresponds to
  the number of rows returned.
</ResponseField>

<ResponseField name="lastInsertId" type="u64">
  This field is available for other database types, but isn't populated for
  PostgreSQL. Instead, use `query` or `queryScalar` with a `RETURNING` clause to
  get the last inserted ID.
</ResponseField>

<ResponseField name="rows" type="T[]">
  An array of objects, each representing a row returned from the query. Each
  object has fields corresponding to the columns in the result set.
</ResponseField>

#### Response

Represents the response from an [`execute`](#execute) operation. Also serves as
the base class for `QueryResponse<T>` and `ScalarResponse<T>`.

```ts
class Response {
  error: string | null
  rowsAffected: u32
  lastInsertId: u64
}
```

<ResponseField name="error" type="string | null">
  An error message, if an error occurred during the operation. Otherwise, this
  field is `null`.
</ResponseField>

<ResponseField name="rowsAffected" type="u32">
  The number of rows affected by the operation.
</ResponseField>

<ResponseField name="lastInsertId" type="u64">
  This field is available for other database types, but isn't populated for
  PostgreSQL. Instead, use `query` or `queryScalar` with a `RETURNING` clause to
  get the last inserted ID.
</ResponseField>

#### ScalarResponse

Represents the response from a [`queryScalar`](#queryscalar) operation.

```ts
class ScalarResponse<T> {
  error: string | null
  rowsAffected: u32
  lastInsertId: u64
  value: T
}
```

<ResponseField name="error" type="string | null">
  An error message, if an error occurred during the operation. Otherwise, this
  field is `null`.
</ResponseField>

<ResponseField name="rowsAffected" type="u32">
  The number of rows affected by the operation, which is typically 1 for a
  scalar query.
</ResponseField>

<ResponseField name="lastInsertId" type="u64">
  This field is available for other database types, but isn't populated for
  PostgreSQL. Instead, use `query` or `queryScalar` with a `RETURNING` clause to
  get the last inserted ID.
</ResponseField>

<ResponseField name="value" type="T">
  The scalar value returned from the query.
</ResponseField>


# Collections APIs
Source: https://docs.hypermode.com/modus/sdk/go/collections

Add storage and vector search capabilities to your functions.

export const SdkHeader = ({language, feature}) => <Note>
    <p>
      While each Modus SDK offers similar capabilities, the APIs and usage may
      vary between languages.
    </p>
    <p>
      Modus {feature} APIs documentation is available on the following pages:
    </p>
    <ul>
      {(() => {
  const languages = ["AssemblyScript", "Go"];
  const page = feature.toLowerCase().replace(/\W/g, "");
  return languages.map(lang => {
    if (lang === language) {
      return <li>
                <b>
                  {lang} {feature} APIs
                </b>{" "}
                (this page)
              </li>;
    } else {
      return <li>
                <a href={`../${lang.toLowerCase()}/${page}`}>
                  {lang} {feature} APIs
                </a>
              </li>;
    }
  });
})()}
    </ul>
  </Note>;

<SdkHeader language="Go" feature="Collections" />

The Modus Collection APIs allow you to add vector search within your functions.

## Import

To begin, import the `collections` package from the SDK:

```go
import "github.com/hypermodeinc/modus/sdk/go/pkg/collections"
```

## Collections APIs

{/* vale Google.Headings = NO */}

The APIs in the `collections` package are below, organized by category.

<Tip>
  We're constantly introducing new APIs through ongoing development with early
  users. Please [open an issue](https://github.com/hypermodeinc/modus/issues) if
  you have ideas on what would make Modus even more powerful for your next app!
</Tip>

### Mutation Functions

#### Upsert

Inserts or updates an item in a collection.

<Note>
  If the item already exists, the function overwrites the previous value. If
  not, it creates a new one.
</Note>

```go
func Upsert(
  collection string,
  key *string,
  text string,
  labels []string,
  opts ...NamespaceOption
) (*CollectionMutationResult, error)
```

<ResponseField name="collection" type="string" required>
  Name of the collection, as [defined in the
  manifest](/modus/app-manifest#collections).
</ResponseField>

<ResponseField name="key" type="*string">
  The unique identifier for the item in the namespace. If `nil`, the function
  generates a unique identifier.
</ResponseField>

<ResponseField name="text" type="string" required>
  The text of the item to add to the collection.
</ResponseField>

<ResponseField name="labels" type="[]string">
  An optional slice of labels to associate with the item.
</ResponseField>

<ResponseField name="opts" type="...NamespaceOption">
  Associates the item with a specific namespace. Defaults to an empty namespace
  if not provided.

  Pass `collections.WithNamespace("namespace")` to specify a namespace.
</ResponseField>

#### UpsertBatch

Inserts or updates a batch of items into a collection.

<Note>
  If an item with the same key already exists, the original text is overwritten
  with the new text.
</Note>

```go
func UpsertBatch(
  collection string,
  keys []string,
  texts []string,
  labelsArr [][]string,
  opts ...NamespaceOption
) (*CollectionMutationResult, error)
```

<ResponseField name="collection" type="string" required>
  Name of the collection, as [defined in the
  manifest](/modus/app-manifest#collections).
</ResponseField>

<ResponseField name="keys" type="[]string">
  Slice of keys for the item to add to the collection. If you pass `nil` for any
  key, Hypermode assigns a new UUID as the key for the item.
</ResponseField>

<ResponseField name="texts" type="[]string" required>
  Slice of texts for the items to add to the collection.
</ResponseField>

<ResponseField name="labelsArr" type="[][]string">
  An optional slice of slices of labels to associate with the items.
</ResponseField>

<ResponseField name="opts" type="...NamespaceOption">
  Associates the item with a specific namespace. Defaults to an empty namespace
  if not provided.

  Pass `collections.WithNamespace("namespace")` to specify a namespace.
</ResponseField>

#### Remove

Removes an item from the collection.

```go
func Remove(
  collection string,
  key string,
  opts ...NamespaceOption
) (*CollectionMutationResult, error)
```

<ResponseField name="collection" type="string" required>
  Name of the collection, as [defined in the
  manifest](/modus/app-manifest#collections).
</ResponseField>

<ResponseField name="key" type="string" required>
  The key of the item to delete from the collection.
</ResponseField>

<ResponseField name="opts" type="...NamespaceOption">
  The namespace to remove the item from. Defaults to the default namespace if
  not provided.

  Pass `collections.WithNamespace("namespace")` to specify a namespace.
</ResponseField>

### Search and Retrieval Functions

#### ComputeDistance

Computes distance between two keys in a collection using a search method's
embedder.

```go
func ComputeDistance(
  collection string,
  searchMethod string,
  key1 string,
  key2 string,
  opts ...NamespaceOption
) (*CollectionSearchResultObject, error)
```

<ResponseField name="collection" type="string" required>
  Name of the collection, as [defined in the
  manifest](/modus/app-manifest#collections).
</ResponseField>

<ResponseField name="searchMethod" type="string" required>
  The search method used to calculate embedding for key's texts.
</ResponseField>

<ResponseField name="key1, key2" type="string" required>
  Keys to compute similarity on.
</ResponseField>

<ResponseField name="opts" type="...NamespaceOption">
  The namespace to search the items from. Defaults to the default namespace if
  not provided.

  Pass `collections.WithNamespace("namespace")` to specify a namespace.
</ResponseField>

#### NnClassify

Classify an item in the collection using previous vectors' labels.

```go
func NnClassify(
  collection string,
  searchMethod string,
  text string,
  opts ...NamespaceOption
) (*CollectionClassificationResult, error)
```

<ResponseField name="collection" type="string" required>
  Name of the collection, as [defined in the
  manifest](/modus/app-manifest#collections).
</ResponseField>

<ResponseField name="searchMethod" type="string" required>
  The search method used to calculate embedding for text & search against.
</ResponseField>

<ResponseField name="text" type="string" required>
  The text to compute natural language search on.
</ResponseField>

<ResponseField name="opts" type="...NamespaceOption">
  The namespace to search the items from. Defaults to the default namespace if
  not provided.

  Pass `collections.WithNamespace("namespace")` to specify a namespace.
</ResponseField>

#### GetLabels

Get the labels for an item in a collection.

```go
func GetLabels(
  collection string,
  key string,
  opts ...NamespaceOption
) ([]string, error)
```

<ResponseField name="collection" type="string" required>
  Name of the collection, as [defined in the
  manifest](/modus/app-manifest#collections).
</ResponseField>

<ResponseField name="key" type="string" required>
  The key of the item to retrieve.
</ResponseField>

<ResponseField name="opts" type="...NamespaceOption">
  The namespace to get the item from. Defaults to the default namespace if not
  provided.

  Pass `collections.WithNamespace("namespace")` to specify a namespace.
</ResponseField>

#### GetNamespaces

Get all namespaces in a collection.

```go
func GetNamespaces(collection string) ([]string, error)
```

<ResponseField name="collection" type="string" required>
  Name of the collection, as [defined in the
  manifest](/modus/app-manifest#collections).
</ResponseField>

#### GetText

Gets an item's text from a collection, give the item's key.

```go
func GetText(
  collection string,
  key string,
  opts ...NamespaceOption
) (string, error)
```

<ResponseField name="collection" type="string" required>
  Name of the collection, as [defined in the
  manifest](/modus/app-manifest#collections).
</ResponseField>

<ResponseField name="key" type="string" required>
  The key of the item to retrieve.
</ResponseField>

<ResponseField name="opts" type="...NamespaceOption">
  The namespace to get the item from. Defaults to the default namespace if not
  provided.

  Pass `collections.WithNamespace("namespace")` to specify a namespace.
</ResponseField>

#### GetTexts

Get all items from a collection. The result is a map of key to text for all
items in the collection.

```go
func GetTexts(
  collection string,
  opts ...NamespaceOption
) (map[string]string, error)
```

<ResponseField name="collection" type="string" required>
  Name of the collection, as [defined in the
  manifest](/modus/app-manifest#collections).
</ResponseField>

<ResponseField name="opts" type="...NamespaceOption">
  The namespace to get the items from. Defaults to the default namespace if not
  provided.

  Pass `collections.WithNamespace("namespace")` to specify a namespace.
</ResponseField>

#### GetVector

Get the vector for an item in a collection.

```go
func GetVector(
  collection string,
  searchMethod string,
  key string,
  opts ...NamespaceOption
) ([]float32, error)
```

<ResponseField name="collection" type="string" required>
  Name of the collection, as [defined in the
  manifest](/modus/app-manifest#collections).
</ResponseField>

<ResponseField name="searchMethod" type="string" required>
  The search method used to calculate embedding for key's texts.
</ResponseField>

<ResponseField name="key" type="string" required>
  The key of the item to retrieve.
</ResponseField>

<ResponseField name="opts" type="...NamespaceOption">
  The namespace to get the item from. Defaults to the default namespace if not
  provided.

  Pass `collections.WithNamespace("namespace")` to specify a namespace.
</ResponseField>

#### Search

Perform a natural language search on items within a collection. This method is
useful for finding items that match a search query based on semantic meaning.

<Note>
  Modus uses the same embedder for both inserting text into the collection, and
  for the text used when searching the collection.
</Note>

```go
func Search(
  collection string,
  searchMethod string,
  text string,
  opts ...SearchOption
) (*CollectionSearchResult, error)
```

<ResponseField name="collection" type="string" required>
  Name of the collection, as [defined in the
  manifest](/modus/app-manifest#collections).
</ResponseField>

<ResponseField name="searchMethod" type="string" required>
  The search method used to calculate embedding for text & search against.
</ResponseField>

<ResponseField name="text" type="string" required>
  The text to compute natural language search on.
</ResponseField>

<ResponseField name="opts" type="...SearchOption">
  Additional options for the search:

  * `collections.WithLimit(limit int)`: The number of result objects to return.
  * `collections.WithReturnText(returnText bool)`: A flag to return the texts in
    the response.
  * `collections.WithNamespaces(namespaces []string)`: A list of namespaces to
    search the item from. Defaults to the default namespace if not provided.
</ResponseField>

#### SearchByVector

Perform a vector-based search on a collection, which is helpful for scenarios
requiring precise similarity calculations between pre-computed embeddings.

<Note>
  Modus uses the same embedder for both inserting text into the collection, and
  for the vector used when searching the collection.
</Note>

```go
func SearchByVector(
  collection string,
  searchMethod string,
  vector []float32,
  opts ...SearchOption
) (*CollectionSearchResult, error)
```

<ResponseField name="collection" type="string" required>
  Name of the collection, as [defined in the
  manifest](/modus/app-manifest#collections).
</ResponseField>

<ResponseField name="searchMethod" type="string" required>
  The search method used to calculate embedding for vector & search against.
</ResponseField>

<ResponseField name="vector" type="[]float32" required>
  The vector to compute search on.
</ResponseField>

<ResponseField name="opts" type="...SearchOption">
  Additional options for the search:

  * `collections.WithLimit(limit int)`: The number of result objects to return.
  * `collections.WithReturnText(returnText bool)`: A flag to return the texts in
    the response.
  * `collections.WithNamespaces(namespaces []string)`: A list of namespaces to
    search the item from. Defaults to the default namespace if not provided.
</ResponseField>

### Maintenance Functions

#### RecomputeSearchMethod

Recalculates the embeddings for all items in a collection. It can be
resource-intensive, use it when necessary, for example after you have updated
the method for embedding calculation and want to re-compute the embeddings for
existing data in the collection.

```go
func RecomputeSearchMethod(
  collection string,
  searchMethod string,
  opts ...NamespaceOption
) (*SearchMethodMutationResult, error)
```

<ResponseField name="collection" type="string" required>
  Name of the collection, as [defined in the
  manifest](/modus/app-manifest#collections).
</ResponseField>

<ResponseField name="searchMethod" type="string" required>
  The search method to recompute embeddings for.
</ResponseField>

<ResponseField name="opts" type="...NamespaceOption">
  The namespace to use. Defaults to the default namespace if not provided.

  Pass `collections.WithNamespace("namespace")` to specify a namespace.
</ResponseField>

### Types

#### CollectionClassificationLabelObject

Represents a classification label.

```go
type CollectionClassificationLabelObject struct {
  Label string
  Confidence float64
}
```

<ResponseField name="Label" type="string">
  The classification label.
</ResponseField>

<ResponseField name="Confidence" type="float64">
  The confidence score of the classification label.
</ResponseField>

#### CollectionClassificationResult

Represents the result of a classification operation on a collection.

```go
type CollectionClassificationResult struct {
  Collection string
  Status string
  Error string
  SearchMethod string
  LabelsResult []*CollectionClassificationLabelObject
  Cluster []*CollectionClassificationResultObject
}
```

<ResponseField name="Collection" type="string">
  Name of the collection.
</ResponseField>

<ResponseField name="Status" type="string">
  The status of the operation.
</ResponseField>

<ResponseField name="Error" type="string">
  Error message, if any.
</ResponseField>

<ResponseField name="SearchMethod" type="string">
  The search method used in the operation.
</ResponseField>

<ResponseField name="LabelsResult" type="[]*CollectionClassificationLabelObject">
  The classification labels.
</ResponseField>

<ResponseField name="Cluster" type="[]*CollectionClassificationResultObject">
  The classification results.
</ResponseField>

#### CollectionClassificationResultObject

Represents an object in the classification results.

```go
type CollectionClassificationResultObject struct {
  Key string
  Labels []string
  Distance float64
  Score float64
}
```

<ResponseField name="Key" type="string">
  The key of the item classified.
</ResponseField>

<ResponseField name="Labels" type="[]string">
  The classification labels.
</ResponseField>

<ResponseField name="Distance" type="float64">
  The distance of the item from the classification labels.
</ResponseField>

<ResponseField name="Score" type="float64">
  The similarity score of the item classified.
</ResponseField>

#### CollectionMutationResult

Represents the result of a mutation operation on a collection.

```go
type CollectionMutationResult struct {
  Collection string
  Status string
  Error string
  Operation string
  Keys []string
}
```

<ResponseField name="Collection" type="string">
  Name of the collection.
</ResponseField>

<ResponseField name="Status" type="string">
  The status of the operation.
</ResponseField>

<ResponseField name="Error" type="string">
  Error message, if any.
</ResponseField>

<ResponseField name="Operation" type="string">
  The operation performed.
</ResponseField>

<ResponseField name="Keys" type="[]string">
  The keys of the items affected by the operation.
</ResponseField>

#### CollectionSearchResult

Represents the result of a search operation on a collection.

```go
type CollectionSearchResult struct {
  Collection string
  Status string
  Error string
  SearchMethod string
  Objects []*CollectionSearchResultObject
}
```

<ResponseField name="Collection" type="string">
  Name of the collection.
</ResponseField>

<ResponseField name="Status" type="string">
  The status of the operation.
</ResponseField>

<ResponseField name="Error" type="string">
  Error message, if any.
</ResponseField>

<ResponseField name="SearchMethod" type="string">
  The search method used in the operation.
</ResponseField>

<ResponseField name="Objects" type="[]*CollectionSearchResultObject">
  The search results.
</ResponseField>

#### CollectionSearchResultObject

Represents an object in the search results.

```go
type CollectionSearchResultObject struct {
  Namespace string
  Key string
  Text string
  Labels []string
  Distance float64
  Score float64
}
```

<ResponseField name="Namespace" type="string">
  The namespace of the item found as part of the search.
</ResponseField>

<ResponseField name="Key" type="string">
  The key of the item found as part of the search.
</ResponseField>

<ResponseField name="Text" type="string">
  The text of the item found as part of the search.
</ResponseField>

<ResponseField name="Distance" type="float64">
  The distance of the item from the search text.
</ResponseField>

<ResponseField name="Score" type="float64">
  The similarity score of the item found, as it pertains to the search.
</ResponseField>

#### CollectionStatus

The status of a collection operation.

```go
type CollectionStatus = string

const (
  Success CollectionStatus = "success"
  Error   CollectionStatus = "error"
)
```

<ResponseField name="Success">The operation was successful.</ResponseField>

<ResponseField name="Error">The operation encountered an error.</ResponseField>

#### SearchMethodMutationResult

Represents the result of a mutation operation on a search method.

```go
type SearchMethodMutationResult struct {
  Collection string
  Status string
  Error string
  Operation string
  SearchMethod string
}
```

<ResponseField name="Collection" type="string">
  Name of the collection.
</ResponseField>

<ResponseField name="Status" type="string">
  The status of the operation.
</ResponseField>

<ResponseField name="Error" type="string">
  Error message, if any.
</ResponseField>

<ResponseField name="Operation" type="string">
  The operation performed.
</ResponseField>

<ResponseField name="SearchMethod" type="string">
  The search method affected by the operation.
</ResponseField>


# Console APIs
Source: https://docs.hypermode.com/modus/sdk/go/console

Capture errors and debugging information in your functions

export const SdkHeader = ({language, feature}) => <Note>
    <p>
      While each Modus SDK offers similar capabilities, the APIs and usage may
      vary between languages.
    </p>
    <p>
      Modus {feature} APIs documentation is available on the following pages:
    </p>
    <ul>
      {(() => {
  const languages = ["AssemblyScript", "Go"];
  const page = feature.toLowerCase().replace(/\W/g, "");
  return languages.map(lang => {
    if (lang === language) {
      return <li>
                <b>
                  {lang} {feature} APIs
                </b>{" "}
                (this page)
              </li>;
    } else {
      return <li>
                <a href={`../${lang.toLowerCase()}/${page}`}>
                  {lang} {feature} APIs
                </a>
              </li>;
    }
  });
})()}
    </ul>
  </Note>;

<SdkHeader language="Go" feature="Console" />

The Modus Console APIs allow you to capture information from your functions,
such as errors and other information that can help you debug your functions.

<Info>
  In addition to the Console APIs, you can also use any standard Go function that
  emits output to `stdout` or `stderr`. The output from these functions are
  available in the runtime logs.

  For example, you may use:

  * `fmt.Println` to write to informational messages to the logs
  * `fmt.Fprintf(os.Stderr, ...)` to write error messages to the logs

  You may also *return* `error` objects from your function, whose messages get
  captured and returned in the GraphQL response.
</Info>

## Import

To begin, import the `console` package from the SDK:

```go
import "github.com/hypermodeinc/modus/sdk/go/pkg/console"
```

## Console APIs

{/* vale Google.Headings = NO */}

The APIs in the `console` package are below, organized by category.

<Tip>
  We're constantly introducing new APIs through ongoing development with early
  users. Please [open an issue](https://github.com/hypermodeinc/modus/issues) if
  you have ideas on what would make Modus even more powerful for your next app!
</Tip>

### Assertion Functions

#### Assert

Asserts that a condition is true, and logs an error if it's not.

```go
func Assert(condition bool, message string)
```

<ResponseField name="condition" type="bool" required>
  The boolean condition to assert.
</ResponseField>

<ResponseField name="message" type="string" required>
  An error message to log, if the assertion is false.
</ResponseField>

### Logging Functions

<Tip>
  For Go, typically you use these logging APIs when you need detailed control of
  the logging level, or when you need to log multi-line messages as a single log
  entry. Otherwise, you can use the standard Go functions from the `fmt` package
  to emit messages to `stdout` or `stderr`.
</Tip>

#### Log

Generate a log message, with no particular logging level.

```go
func Log(message string)
```

<ResponseField name="message" type="string" required>
  A message you want to log.
</ResponseField>

#### Logf

Generate a message using Go format specifiers and logs the message, with no
particular logging level.

```go
func Logf(message string, args ...any)
```

<ResponseField name="message" type="string" required>
  A message you want to log.
</ResponseField>

<ResponseField name="args" type="...any">
  Arguments that correspond to the format specifiers in the message.
</ResponseField>

#### Debug

Generate a log message with the "debug" logging level.

```go
func Debug(message string)
```

<ResponseField name="message" type="string" required>
  A debug message you want to log.
</ResponseField>

#### Debugf

Generate a message using Go format specifiers and logs the message with the
"debug" logging level.

```go
func Debugf(message string, args ...any)
```

<ResponseField name="message" type="string" required>
  A debug message you want to log.
</ResponseField>

<ResponseField name="args" type="...any">
  Arguments that correspond to the format specifiers in the message.
</ResponseField>

#### Info

Generate a log message with the "info" logging level.

```go
func Info(message string)
```

<ResponseField name="message" type="string" required>
  An informational message you want to log.
</ResponseField>

#### Infof

Generate a message using Go format specifiers and logs the message with the
"info" logging level.

```go
func Infof(message string, args ...any)
```

<ResponseField name="message" type="string" required>
  An informational message you want to log.
</ResponseField>

<ResponseField name="args" type="...any">
  Arguments that correspond to the format specifiers in the message.
</ResponseField>

#### Warn

Generate a log message with the "warning" logging level.

```go
func Warn(message string)
```

<ResponseField name="message" type="string" required>
  A warning message you want to log.
</ResponseField>

#### Warnf

Generate a message using Go format specifiers and logs the message with the
"warning" logging level.

```go
func Warnf(message string, args ...any)
```

<ResponseField name="message" type="string" required>
  A warning message you want to log.
</ResponseField>

<ResponseField name="args" type="...any">
  Arguments that correspond to the format specifiers in the message.
</ResponseField>

#### Error

Generate a log message with the "error" logging level.

```go
func Error(message string)
```

<ResponseField name="message" type="string" required>
  An error message you want to log.
</ResponseField>

#### Errorf

Generate a message using Go format specifiers and logs the message with the
"error" logging level.

```go
func Errorf(message string, args ...any)
```

<ResponseField name="message" type="string" required>
  An error message you want to log.
</ResponseField>

<ResponseField name="args" type="...any">
  Arguments that correspond to the format specifiers in the message.
</ResponseField>

### Timing Functions

#### Time

Starts a new timer using the specified label.

```go
func Time(label ...string)
```

<ResponseField name="label" type="string">
  An optional label for the timer.
</ResponseField>

#### TimeLog

Logs the current value of a timer previously started with `console.Time`.

```go
func TimeLog(label string)
```

<ResponseField name="label" type="string">
  An optional label for the timer.
</ResponseField>

#### TimeEnd

Logs the current value of a timer previously started with `console.Time`, and
discards the timer.

```go
func TimeEnd(label string)
```

<ResponseField name="label" type="string">
  An optional label for the timer.
</ResponseField>


# Dgraph APIs
Source: https://docs.hypermode.com/modus/sdk/go/dgraph

Execute queries and mutations against a Dgraph database

export const SdkHeader = ({language, feature}) => <Note>
    <p>
      While each Modus SDK offers similar capabilities, the APIs and usage may
      vary between languages.
    </p>
    <p>
      Modus {feature} APIs documentation is available on the following pages:
    </p>
    <ul>
      {(() => {
  const languages = ["AssemblyScript", "Go"];
  const page = feature.toLowerCase().replace(/\W/g, "");
  return languages.map(lang => {
    if (lang === language) {
      return <li>
                <b>
                  {lang} {feature} APIs
                </b>{" "}
                (this page)
              </li>;
    } else {
      return <li>
                <a href={`../${lang.toLowerCase()}/${page}`}>
                  {lang} {feature} APIs
                </a>
              </li>;
    }
  });
})()}
    </ul>
  </Note>;

<SdkHeader language="Go" feature="Dgraph" />

The Modus Dgraph APIs allow you to run queries and mutations against a Dgraph
database.

## Import

To begin, import the `dgraph` package from the SDK:

```go
import "github.com/hypermodeinc/modus/sdk/go/pkg/dgraph"
```

## Dgraph APIs

{/* vale Google.Headings = NO */}

The APIs in the `dgraph` package are below, organized by category.

<Tip>
  We're constantly introducing new APIs through ongoing development with early
  users. Please [open an issue](https://github.com/hypermodeinc/modus/issues) if
  you have ideas on what would make Modus even more powerful for your next app!
</Tip>

### Functions

#### AlterSchema

Alter the schema of a Dgraph database.

```go
func AlterSchema(connection, schema string) error
```

<ResponseField name="connection" type="string" required>
  Name of the connection, as [defined in the
  manifest](/modus/app-manifest#connections).
</ResponseField>

<ResponseField name="schema" type="string" required>
  The schema to apply to the Dgraph database.
</ResponseField>

#### DropAll

Drop all data from a Dgraph database.

```go
func DropAll(connection string) error
```

<ResponseField name="connection" type="string" required>
  Name of the connection, as [defined in the
  manifest](/modus/app-manifest#connections).
</ResponseField>

#### DropAttr

Drop an attribute from a Dgraph schema.

```go
func DropAttr(connection, attr string) error
```

<ResponseField name="connection" type="string" required>
  Name of the connection, as [defined in the
  manifest](/modus/app-manifest#connections).
</ResponseField>

<ResponseField name="attr" type="string" required>
  The attribute to drop from the Dgraph schema.
</ResponseField>

#### EscapeRDF

Ensures proper escaping of RDF string literals.

```go
func EscapeRDF(value string) string
```

<ResponseField name="value" type="string" required>
  The RDF string literal to escape.
</ResponseField>

#### ExecuteMutations

Execute one or more mutations, without a filtering query.

<Tip>
  If you need to filter the mutations based on a query, use the
  [`ExecuteQuery`](#executequery) function instead, and pass the mutations after
  the query.
</Tip>

```go
func ExecuteMutations(
  connection string,
  mutations ...*Mutation
) (*Response, error)
```

<ResponseField name="connection" type="string" required>
  Name of the connection, as [defined in the
  manifest](/modus/app-manifest#connections).
</ResponseField>

<ResponseField name="mutations" type="...*Mutation" required>
  One or more pointers to [`Mutation`](#mutation) objects to execute.
</ResponseField>

#### ExecuteQuery

Execute a DQL query to retrieve data from a Dgraph database.

Also used to execute a filtering query and apply one or more mutations to the
result of the query.

<Tip>
  If you need apply mutations *without* a filtering query, use the
  [`ExecuteMutations`](#executemutations) function instead.
</Tip>

```go
func ExecuteQuery(
  connection string,
  query *Query,
  mutations ...*Mutation
) (*Response, error)
```

<ResponseField name="connection" type="string" required>
  Name of the connection, as [defined in the
  manifest](/modus/app-manifest#connections).
</ResponseField>

<ResponseField name="request" type="*Query*" required>
  A pointer to a [`Query`](#query) object describing the DQL query to execute.
</ResponseField>

<ResponseField name="mutations" type="...*Mutation">
  Optional parameters specifying pointers to one or more [`Mutation`](#mutation)
  objects to execute on the nodes matched by the query.
</ResponseField>

#### NewMutation

Creates a new [`Mutation`](#mutation) object.

```go
func NewMutation() *Mutation
```

#### NewQuery

Creates a new [`Query`](#query) object from a DQL query string.

```go
func NewQuery(query string) *Query
```

<ResponseField name="query" type="string" required>
  The DQL query to execute.
</ResponseField>

### Types

#### Mutation

A Dgraph mutation object, used to execute mutations.

```go
type Mutation struct {
  SetJson   string
  DelJson   string
  SetNquads string
  DelNquads string
  Condition string
}

// methods
func (*Mutation) WithSetJson(json string) *Mutation
func (*Mutation) WithDelJson(json string) *Mutation
func (*Mutation) WithSetNquads(nquads string) *Mutation
func (*Mutation) WithDelNquads(nquads string) *Mutation
func (*Mutation) WithCondition(cond string) *Mutation
```

<ResponseField name="SetJson" type="string">
  A JSON string representing the data to set in the mutation.
</ResponseField>

<ResponseField name="DelJson" type="string">
  A JSON string representing the data to delete in the mutation.
</ResponseField>

<ResponseField name="SetNquads" type="string">
  A string representing the data to set in the mutation in RDF N-Quads format.
</ResponseField>

<ResponseField name="DelNquads" type="string">
  A string representing the data to delete in the mutation in RDF N-Quads
  format.
</ResponseField>

<ResponseField name="Condition" type="string">
  A string representing the condition query for the mutation, as a DQL `@if`
  directive.
</ResponseField>

<ResponseField name="condition" type="string">
  A string representing the condition query for the mutation, as a DQL `@if`
  directive.
</ResponseField>

<ResponseField name="WithSetJson(json)">
  Sets the `SetJson` field of the mutation to the given `json` string. Returns
  the `Mutation` object to allow for method chaining.
</ResponseField>

<ResponseField name="WithDelJson(json)">
  Sets the `DelJson` field of the mutation to the given `json` string. Returns
  the `Mutation` object to allow for method chaining.
</ResponseField>

<ResponseField name="WithSetNquads(nquads)">
  Sets the `SetNquads` field of the mutation to the given `nquads` string.
  Returns the `Mutation` object to allow for method chaining.
</ResponseField>

<ResponseField name="WithDelNquads(nquads)">
  Sets the `DelNquads` field of the mutation to the given `nquads` string.
  Returns the `Mutation` object to allow for method chaining.
</ResponseField>

<ResponseField name="WithCondition(cond)">
  Sets the `condition` field of the mutation to the given `cond` string, which
  should be a DQL `@if` directive. Returns the `Mutation` object to allow for
  method chaining.
</ResponseField>

#### Query

A Dgraph query object, used to execute queries.

```go
type Query struct {
  Query     string
  Variables map[string]string
}

// methods
func (*Query) WithVariable(key string, value any) *Query
```

<ResponseField name="Query" type="string">
  The DQL query to execute.
</ResponseField>

<ResponseField name="Variables" type="map[string]string">
  A map of query variables, with values encoded as strings.
</ResponseField>

<ResponseField name="WithVariable(name, value)">
  Sets a query variable with the given `name` and `value`. `name` is of type
  `string`, and `value` can be a string, number, or boolean.

  Returns the `*Query` object to allow for method chaining.

  <Tip>
    The `WithVariable` method is the preferred way to set query variables in a
    `Query` object, and allows for fluent method chaining to add multiple variables.
    For example:

    ```go
    query := NewQuery(`
      query all($name: string, $age: int) {
        all(func: eq(name, $name)) {
          name
          age
        }
      }
    `).
      WithVariable("name", "Alice").
      WithVariable("age", 30)

    response := dgraph.ExecuteQuery("my-dgraph-connection", query)
    ```
  </Tip>
</ResponseField>

#### Request

A Dgraph request object, used to execute queries and mutations.

<Info>
  {/* vale Google.Passive = NO */}

  This object was used by the `Execute` function, which has been replaced by the
  [`ExecuteQuery`](#executequery) and [`ExecuteMutations`](#executemutations)
  functions. You should no longer need to create a `Request` object directly.

  {/* vale Google.Passive = YES */}
</Info>

```go
type Request struct {
  Query     *Query
  Mutations []*Mutation
}
```

<ResponseField name="Query" type="*Query">
  A pointer to a Dgraph [`query`](#query) object.
</ResponseField>

<ResponseField name="Mutations" type="[]*Mutation">
  An slice of pointers to Dgraph [`mutation`](#mutation) objects.
</ResponseField>


# GraphQL APIs
Source: https://docs.hypermode.com/modus/sdk/go/graphql

Access external GraphQL data sources from your functions

export const SdkHeader = ({language, feature}) => <Note>
    <p>
      While each Modus SDK offers similar capabilities, the APIs and usage may
      vary between languages.
    </p>
    <p>
      Modus {feature} APIs documentation is available on the following pages:
    </p>
    <ul>
      {(() => {
  const languages = ["AssemblyScript", "Go"];
  const page = feature.toLowerCase().replace(/\W/g, "");
  return languages.map(lang => {
    if (lang === language) {
      return <li>
                <b>
                  {lang} {feature} APIs
                </b>{" "}
                (this page)
              </li>;
    } else {
      return <li>
                <a href={`../${lang.toLowerCase()}/${page}`}>
                  {lang} {feature} APIs
                </a>
              </li>;
    }
  });
})()}
    </ul>
  </Note>;

<SdkHeader language="Go" feature="GraphQL" />

The Modus GraphQL APIs allow you to securely call and fetch data from any
GraphQL endpoint.

## Import

To begin, import the `graphql` package from the SDK:

```go
import "github.com/hypermodeinc/modus/sdk/go/pkg/graphql"
```

## GraphQL APIs

{/* vale Google.Headings = NO */}

The APIs in the `graphql` package are below, organized by category.

<Tip>
  We're constantly introducing new APIs through ongoing development with early
  users. Please [open an issue](https://github.com/hypermodeinc/modus/issues) if
  you have ideas on what would make Modus even more powerful for your next app!
</Tip>

### Functions

#### Execute

Execute a GraphQL statement to call a query or apply mutation against a GraphQL
endpoint.

```go
Execute[T any](
  connection,
  statement string,
  variables map[string]any
) (*Response[T], error)
```

<ResponseField name="T" required>
  Type of object to use for the data returned from the query. This can be any
  type, including a custom type defined in your project. It should match the shape
  of the data returned from the GraphQL query.

  <Tip>
    Define custom types in the project's source code. All types must be JSON
    serializable. You can also use built-in types such as strings, numbers,
    slices, and maps.
  </Tip>
</ResponseField>

<ResponseField name="connection" type="string" required>
  Name of the connection, as [defined in the
  manifest](/modus/app-manifest#connection).
</ResponseField>

<ResponseField name="statement" type="string" required>
  GraphQL statement containing the query or mutation operation to execute.

  <Warning>
    While it's possible to directly include parameter values into your GraphQL
    statement, it's highly recommended to pass a variables map instead. This can
    help to prevent against injection attacks and other security vulnerabilities.
  </Warning>
</ResponseField>

<ResponseField name="variables" type="map[string]any">
  Optional variables to include with the query.

  The key should be the name of the GraphQL variable. The value can be of any type
  that's JSON serializable, including strings, numbers, boolean values, slices,
  maps, and custom structs.
</ResponseField>

### Types

#### Response

```go
type Response[T any] struct {
  Errors []ErrorResult
  Data   *T
}
```

A response object from the GraphQL query.

Either `Errors` or `Data` is present, depending on the result of the query.

<ResponseField name="Errors" type="[]ErrorResult">
  An slice of errors incurred as part of your GraphQL request, if any.

  Each error in the slice is an [`ErrorResult`](#errorresult) object. If there are
  no errors, this field is `nil`.
</ResponseField>

<ResponseField name="Data" type="*T">
  The resulting data selected by the GraphQL operation.

  The data is a pointer to an object the type specified in the call to the
  `Execute` function. If data is absent due to errors, this field is `nil`.
</ResponseField>

#### ErrorResult

```go
type ErrorResult struct {
  Message   string
  Locations []CodeLocation
  Path      []string
}
```

The details of an error incurred as part of a GraphQL operation.

<ResponseField name="Message" type="string">
  Description of the error incurred.
</ResponseField>

<ResponseField name="Path" type="[]string">
  Path to the area of the GraphQL statement related to the error.

  Each item in the slice represents a segment of the path.
</ResponseField>

<ResponseField name="Locations" type="[]CodeLocation">
  An slice of [`CodeLocation`](#codelocation) objects that point to the specific
  location of the error in the GraphQL statement.
</ResponseField>

#### CodeLocation

```go
type CodeLocation struct {
  Line   uint32
  Column uint32
}
```

The location of specific code within a GraphQL statement.

<ResponseField name="Line" type="uint32">
  Line number within the GraphQL statement for the code.
</ResponseField>

<ResponseField name="Column" type="uint32">
  Column number within the GraphQL statement for the code.
</ResponseField>


# HTTP APIs
Source: https://docs.hypermode.com/modus/sdk/go/http

Access external HTTP endpoints from your functions

export const SdkHeader = ({language, feature}) => <Note>
    <p>
      While each Modus SDK offers similar capabilities, the APIs and usage may
      vary between languages.
    </p>
    <p>
      Modus {feature} APIs documentation is available on the following pages:
    </p>
    <ul>
      {(() => {
  const languages = ["AssemblyScript", "Go"];
  const page = feature.toLowerCase().replace(/\W/g, "");
  return languages.map(lang => {
    if (lang === language) {
      return <li>
                <b>
                  {lang} {feature} APIs
                </b>{" "}
                (this page)
              </li>;
    } else {
      return <li>
                <a href={`../${lang.toLowerCase()}/${page}`}>
                  {lang} {feature} APIs
                </a>
              </li>;
    }
  });
})()}
    </ul>
  </Note>;

<SdkHeader language="Go" feature="HTTP" />

The Modus HTTP APIs allow you to securely call and fetch data from an HTTP
endpoint. It's similar to the HTTP
[`fetch`](https://developer.mozilla.org/docs/Web/API/Fetch_API) API used in
JavaScript, but with some modifications to work with Modus.

In a future version of Modus, we'll support Go's standard `net/http` package for
making HTTP requests. However, that's currently not supported due to technical
limitations.

<Warning>
  As a security measure, you can only call HTTP endpoints that you
  [defined in your app's manifest](/modus/app-manifest#connections). Any attempt
  to access an arbitrary URL, for a connection not defined in your app's manifest,
  results in an error.

  Additionally, you should use placeholders for connection secrets in the
  manifest, rather than hardcoding them in your functions. Enter the values for
  each connections' secrets via environment variables or the Hypermode UI. This
  ensures that your secrets are securely stored, aren't committed to your
  repository, and aren't visible or accessible from your functions code.
</Warning>

## Import

To begin, import the `http` package from the SDK:

```go
import "github.com/hypermodeinc/modus/sdk/go/pkg/http"
```

## HTTP APIs

{/* vale Google.Headings = NO */}

The APIs in the `http` package are below, organized by category.

<Tip>
  We're constantly introducing new APIs through ongoing development with early
  users. Please [open an issue](https://github.com/hypermodeinc/modus/issues) if
  you have ideas on what would make Modus even more powerful for your next app!
</Tip>

### Functions

#### Fetch

Invoke an HTTP endpoint to retrieve data or trigger external action.

Returns a [`Response`](#response) object with the HTTP response data.

```go
func Fetch[T *Request | string](
  requestOrUrl T,
  options ...*RequestOptions
) (*Response, error)
```

<ResponseField name="requestOrUrl" type="*Request | string" required>
  Either a URL `string` or a pointer to a [`Request`](#request) object, describing
  the HTTP request to make.

  If a `string`, the operation uses the `GET` HTTP method with no headers other
  than those defined in the manifest entry of the connection.

  <Note>
    Each request must match to a connection entry in the manifest, using the
    `baseUrl` field. The request URL passed to the `Fetch` function (or via a
    `Request` object) must start with the manifest entry's `baseUrl` value to
    match.
  </Note>
</ResponseField>

<ResponseField name="options" type="*RequestOptions">
  An optional pointer to a [`RequestOptions`](#requestoptions) object with
  additional options for the request, such as the HTTP method, headers, and
  body.
</ResponseField>

#### NewContent

Creates a new [`Content`](#content) object from the given `value`, and returns a
pointer to it.

```go
func NewContent(value any) *Content
```

<ResponseField name="value" required>
  The value to create the `Content` object from. Must be one of the following
  types:

  * A [`Content`](#content) object, or a pointer to one.
  * A `[]byte` of binary content, or a pointer to one.
  * A `string` of text content.
  * Any other object that's JSON serializable. The content then becomes the JSON
    representation of the object.
</ResponseField>

#### NewHeaders

Creates a new [`Headers`](#headers) object from the given `value`, and returns a
pointer to it.

```go
func NewHeaders[T [][]string | map[string]string | map[string][]string](
  value T
) *Headers
```

<ResponseField name="value" type="[][]string | map[string]string | map[string][]string" required>
  The value object to create the [`Headers`](#headers) object from. Must be one of
  the following types:

  * A `[][]string`, where each inner slice contains a header name and value.
  * A `map[string]string`, where the keys are header names and the values are
    header values.
  * A `map[string][]string`, where the keys are header names and the values are
    slices of header values.
</ResponseField>

#### NewRequest

Creates a new [`Request`](#request) object with the given `url` and `options`,
and returns a pointer to it.

```go
func NewRequest(url string, options ...*RequestOptions) *Request
```

<ResponseField name="url" type="string" required>
  The fully qualified URL of the request, including the protocol. For example,
  `"https://example.com"`.
</ResponseField>

<ResponseField name="options" type="*RequestOptions">
  An optional pointer to a [`RequestOptions`](#requestoptions) object that's
  used to set the HTTP method, headers, and body if needed.
</ResponseField>

### Types

#### Content

Represents content used in the body of an HTTP request or response.

<Tip>
  Use the [`NewContent`](#newcontent) function to create a new `Content` object.
</Tip>

```go
type Content struct {
  // no exported fields
}

// methods
func (*Content) Bytes() []byte
func (*Content) Text() string
func (*Content) JSON(result any) error
```

<ResponseField name="Bytes()">
  Returns the binary content as a byte slice.
</ResponseField>

<ResponseField name="Text()">
  Interprets the content as a UTF-8 encoded string, and returns it as a `string`
  value.
</ResponseField>

<ResponseField name="JSON(result any) error">
  Interprets the content as a UTF-8 encoded string containing JSON, and attempts
  to deserialize it into the `result` provided.

  Pass the `result` as a pointer to an object matching the shape of the JSON. For
  example:

  ```go
  var data MyData
  if err := content.JSON(&data); err != nil {
    // handle error
  }
  ```
</ResponseField>

#### Header

Represents an HTTP request or response header.

```go
type Header struct {
  Name   string
  Values []string
}
```

<ResponseField name="Name" type="string">
  The name of the header.
</ResponseField>

<ResponseField name="Values" type="[]string">
  An slice of values for the header. Typically a header has a single value, but
  some headers can have multiple values.
</ResponseField>

#### Headers

Represents a collection of HTTP headers.

<Tip>
  Use the [`NewHeaders`](#newheaders) function to create a new `Headers` object.
</Tip>

```go
type Headers struct {
  // no exported fields
}

// methods
func (*Headers) Append(name, value string)
func (*Headers) Entries() [][]string
func (*Headers) Get(name string) *string
```

<ResponseField name="Append(name, value)">
  Appends a new header with the given `name` and `value` to the collection.
</ResponseField>

<ResponseField name="Entries()">
  Returns a `[][]string`, where each inner slice contains a header name and
  value.
</ResponseField>

<ResponseField name="Get(name)">
  Returns the value of the header with the given `name`, or `nil` if the header
  doesn't exist. If there are multiple values for the header, this function
  concatenates them with a comma to form a single string.
</ResponseField>

#### Request

Represents an HTTP request to make.

<Tip>
  Use the [`NewRequest`](#newrequest) function to create a new `Request` object.
</Tip>

```go
type Request struct {
  Url     string
  Method  string
  Headers *Headers
  Body    []byte
}

// methods
func (*Request) Clone(options ...*RequestOptions) *Request
func (*Request) Bytes() []byte
func (*Request) Text() string
func (*Request) JSON(result any) error
```

<ResponseField name="Url" type="string">
  The fully qualified URL of the request, including the protocol. For example,
  `"https://example.com"`.
</ResponseField>

<ResponseField name="Method" type="string">
  The HTTP method of the request. For example, `"GET"`, `"POST"`, `"PUT"`, or
  `"DELETE"`.
</ResponseField>

<ResponseField name="Headers" type="Headers">
  The HTTP headers of the request, as a pointer to a [`Headers`](#headers)
  object.
</ResponseField>

<ResponseField name="Body" type="[]byte">
  The raw binary content data of the request body.

  <Tip>
    The request body isn't normally read directly. Instead, use the `Bytes`,
    `Text`, or `JSON` methods.
  </Tip>
</ResponseField>

<ResponseField name="Clone(options)">
  Clones the `Request` object, applies the `options` to the new object, and
  returns it.
</ResponseField>

<ResponseField name="Bytes()">
  Returns the binary content of the request body as a byte slice.
</ResponseField>

<ResponseField name="Text()">
  Interprets the content of the request body as a UTF-8 encoded string, and
  returns it as a `string` value.
</ResponseField>

<ResponseField name="JSON(result any) error">
  Interprets the content of the request body as a UTF-8 encoded string containing
  JSON, and attempts to deserialize it into the `result` provided.

  Pass the `result` as a pointer to an object matching the shape of the JSON. For
  example:

  ```go
  var data MyData
  if err := request.JSON(&data); err != nil {
    // handle error
  }
  ```
</ResponseField>

#### RequestOptions

Options for the HTTP request.

```go
type RequestOptions struct {
  Method  string
  Headers any
  Body    any
}
```

<ResponseField name="Method" type="string">
  The HTTP method of the request. For example, `"GET"`, `"POST"`, `"PUT"`, or
  `"DELETE"`. If empty, the request uses the `GET` method.
</ResponseField>

<ResponseField name="Headers">
  The HTTP headers of the request, which must be of one of the following types:

  * A [`Headers`](#headers) object, or a pointer to one.
  * A `[][]string`, where each inner slice contains a header name and value.
  * A `map[string]string`, where the keys are header names and the values are
    header values.
  * A `map[string][]string`, where the keys are header names and the values are
    slices of header values.
</ResponseField>

<ResponseField name="Body" type="any">
  Content to pass in the request body. Must be one of the following types:

  * A [`Content`](#content) object, or a pointer to one.
  * A `[]byte` of binary content, or a pointer to one.
  * A `string` of text content.
  * `nil` if there is no body to pass.

  <Tip>
    It's generally recommended to supply a `Content-Type` header for any requests
    that have a body.
  </Tip>
</ResponseField>

#### Response

Represents the response received from the HTTP server.

```go
type Response struct {
  Status     uint16
  StatusText string
  Headers    *Headers
  Body       []byte
}

// methods
func (*Response) Ok() bool
func (*Response) Bytes() []byte
func (*Response) Text() string
func (*Response) JSON(result any) error
```

<ResponseField name="Status" type="uint16">
  The HTTP response status code, such as `200` for success.
</ResponseField>

<ResponseField name="StatusText" type="string">
  The HTTP response status text associated with the status code, such as `"OK"`
  for success.
</ResponseField>

<ResponseField name="Headers" type="*Headers">
  The HTTP headers received with the response, as a pointer to a
  [`Headers`](#headers) object.
</ResponseField>

<ResponseField name="Body" type="[]byte">
  The raw binary content data of the response body.

  <Tip>
    The response body isn't normally read directly. Instead, use the `Bytes`,
    `Text`, or `JSON` methods.
  </Tip>
</ResponseField>

<ResponseField name="Bytes()">
  Returns the binary content of the response body as a byte slice.
</ResponseField>

<ResponseField name="Text()">
  Interprets the content of the response body as a UTF-8 encoded string, and
  returns it as a `string` value.
</ResponseField>

<ResponseField name="JSON(result any) error">
  Interprets the content of the response body as a UTF-8 encoded string containing
  JSON, and attempts to deserialize it into the `result` provided.

  Pass the `result` as a pointer to an object matching the shape of the JSON. For
  example:

  ```go
  var data MyData
  if err := response.JSON(&data); err != nil {
    // handle error
  }
  ```
</ResponseField>


# Local Time APIs
Source: https://docs.hypermode.com/modus/sdk/go/localtime

Access the user's local time and time zone in your functions

export const SdkHeader = ({language, feature}) => <Note>
    <p>
      While each Modus SDK offers similar capabilities, the APIs and usage may
      vary between languages.
    </p>
    <p>
      Modus {feature} APIs documentation is available on the following pages:
    </p>
    <ul>
      {(() => {
  const languages = ["AssemblyScript", "Go"];
  const page = feature.toLowerCase().replace(/\W/g, "");
  return languages.map(lang => {
    if (lang === language) {
      return <li>
                <b>
                  {lang} {feature} APIs
                </b>{" "}
                (this page)
              </li>;
    } else {
      return <li>
                <a href={`../${lang.toLowerCase()}/${page}`}>
                  {lang} {feature} APIs
                </a>
              </li>;
    }
  });
})()}
    </ul>
  </Note>;

<SdkHeader language="Go" feature="Local Time" />

The Modus Local Time APIs allow you to access the user's local time and time
zone from your functions.

## Import

To begin, import the `localtime` package from the SDK:

```go
import "github.com/hypermodeinc/modus/sdk/go/pkg/localtime"
```

{/* vale Google.Headings = NO */}

## Local Time APIs

The APIs in the `localtime` package are below.

All time zones use the IANA time zone database format. For example,
`"America/New_York"`. You can find a list of valid time zones
[here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).

<Info>
  {/* vale Google.Passive = NO */}

  For APIs that work with the user's local time, the time zone is determined in
  the following order of precedence:

  * If the `X-Time-Zone` header is present in the request, the time zone is set to
    the value of the header.
  * If the `TZ` environment variable is set on the host, the time zone is set to
    the value of the variable.
  * Otherwise, the time zone is set to the host's local time zone.

  {/* vale Google.Passive = YES */}
</Info>

<Tip>
  When working locally with `modus dev`, Modus uses the host's local time zone by
  default. You can override this by setting the `TZ` environment variable in your
  `.env.local` file.
</Tip>

<Tip>
  In a browser-based web app, you can get the user's time zone with the following
  JavaScript code:

  ```js
  const timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone
  ```

  Assign that value to a `"X-Time-Zone"` request header when calling Modus, to use
  it for all local time calculations.
</Tip>

<Tip>
  In many cases, you can use Go's built-in time support:

  ```go
  // to get the current time in UTC
  now := time.Now().UTC()

  // if you need a string
  s := now.Format(time.RFC3339)
  ```
</Tip>

<Warning>
  Due to Go's WASM implementation, the standard `time.Now()` function always
  returns the UTC time, not the user's local time like it usually does in Go. If
  you need the user's local time, use `localtime.Now()` instead.
</Warning>

<Tip>
  We're constantly introducing new APIs through ongoing development with early
  users. Please [open an issue](https://github.com/hypermodeinc/modus/issues) if
  you have ideas on what would make Modus even more powerful for your next app!
</Tip>

### Functions

#### GetLocation

Returns a pointer to a Go `time.Location` object for a specific time zone.
Errors if the time zone provided is invalid.

```go
func GetLocation(tz string) (*time.Location, error)
```

#### GetTimeZone

Returns the user's time zone in IANA format.

```go
func GetTimeZone() string
```

#### IsValidTimeZone

Determines whether the specified time zone is a valid IANA time zone and
recognized by the system as such.

```go
func IsValidTimeZone(tz string) bool
```

<ResponseField name="tz" type="string" required>
  An IANA time zone identifier, such as `"America/New_York"`.
</ResponseField>

#### Now

Returns the current time as a `time.Time` object, with the location set to the
user's local time zone. Errors if the time zone passed to the host is invalid.

```go
func Now() (time.Time, error)
```

#### NowInZone

Returns the current time as a `time.Time` object, with the location set to a
specific time zone. Errors if the time zone provided is invalid.

```go
func NowInZone(tz string) (time.Time, error)
```

<ResponseField name="tz" type="string" required>
  An IANA time zone identifier, such as `"America/New_York"`.
</ResponseField>


# AI Model APIs
Source: https://docs.hypermode.com/modus/sdk/go/models

Invoke AI models from your functions

export const SdkHeader = ({language, feature}) => <Note>
    <p>
      While each Modus SDK offers similar capabilities, the APIs and usage may
      vary between languages.
    </p>
    <p>
      Modus {feature} APIs documentation is available on the following pages:
    </p>
    <ul>
      {(() => {
  const languages = ["AssemblyScript", "Go"];
  const page = feature.toLowerCase().replace(/\W/g, "");
  return languages.map(lang => {
    if (lang === language) {
      return <li>
                <b>
                  {lang} {feature} APIs
                </b>{" "}
                (this page)
              </li>;
    } else {
      return <li>
                <a href={`../${lang.toLowerCase()}/${page}`}>
                  {lang} {feature} APIs
                </a>
              </li>;
    }
  });
})()}
    </ul>
  </Note>;

<SdkHeader language="Go" feature="Models" />

The Modus Models APIs allow you to invoke AI models directly from your
functions, irrespective of the model's host.

Since many models have unique interfaces, the design of the Models APIs are
extremely flexible. An interface and common base type forms the core of the
APIs, which extends to conform to any model's required schema.

The SDK contains both the base types and pre-defined implementations for many
commonly used models. You can either use one of the pre-defined model types, or
can create custom types for any model you like, by following the same pattern as
implemented in the pre-defined models.

<Tip>
  For your reference, several complete examples for using the Models APIs are available in
  [Model Invoking](/modus/model-invoking).

  Each example demonstrates using different types of AI models for different
  purposes. However, the Models interface isn't limited to these purposes. You can
  use it for any task that an AI model can perform.
</Tip>

## Import

To begin, import the `models` package from the SDK:

```go
import "github.com/hypermodeinc/modus/sdk/go/pkg/models"
```

You'll also need to import one or more packages for the model you are working
with. For example:

```go
import "github.com/hypermodeinc/modus/sdk/go/pkg/models/openai"
```

If you would like to request a new model, please
[open an issue](https://github.com/hypermodeinc/modus/issues). You can also send
a pull request, if you'd like to contribute a new model yourself.

## Models APIs

{/* vale Google.Headings = NO */}

The APIs in the `models` package are below, organized by category.

<Tip>
  We're constantly introducing new APIs through ongoing development with early
  users. Please [open an issue](https://github.com/hypermodeinc/modus/issues) if
  you have ideas on what would make Modus even more powerful for your next app!
</Tip>

### Functions

#### GetModel

Get a model instance by name and type.

```go
func GetModel[TModel](modelName string) (*TModel, error)
```

<ResponseField name="TModel" required>
  The type of model to return. This can be any struct that implements the
  `Model` interface.
</ResponseField>

<ResponseField name="modelName" type="string" required>
  The name of the model to retrieve. This must match the name of a model defined
  in your project's manifest file.
</ResponseField>

### Types

#### Model

The interface that all Modus models must implement.

```go
type Model[TIn, TOut any] interface {
  Info() *ModelInfo
  Invoke(input *TIn) (*TOut, error)
}
```

<ResponseField name="TIn" required>
  The type of the input data for the model. This can be any type, including a
  custom type defined in your project. It should match the shape of the data
  expected by the model. It's usually a struct.
</ResponseField>

<ResponseField name="TOut" required>
  The type of the output data from the model. This can be any type, including a
  custom type defined in your project. It should match the shape of the data
  returned by the model. It's usually a struct.
</ResponseField>

<ResponseField name="Info()" type="method">
  Returns information about the model set by the Modus Runtime when creating the
  instance. See the [`ModelInfo`](#modelinfo) object for more information.
</ResponseField>

<ResponseField name="Invoke(input)" type="method">
  Invokes the model with input data and returns the output data.
</ResponseField>

#### ModelBase

The base type for all models that Modus functions can invoke.

<Tip>
  If you are implementing a custom model, you'll need to create a type alias
  based on this struct. You'll also need structs to represent the input and
  output types for your model. See the implementations of the pre-defined models
  in the Modus GitHub repository for examples.
</Tip>

```go
type ModelBase[TIn, TOut any] struct {
  Debug bool
}

// methods
func (ModelBase[TIn, TOut]) Info() *ModelInfo
func (ModelBase[TIn, TOut]) Invoke(input *TIn) (*TOut, error)
```

<ResponseField name="TIn" required>
  The type of the input data for the model. This can be any type, including a
  custom type defined in your project. It should match the shape of the data
  expected by the model. It's usually a struct.
</ResponseField>

<ResponseField name="TOut" required>
  The type of the output data from the model. This can be any type, including a
  custom type defined in your project. It should match the shape of the data
  returned by the model. It's usually a struct.
</ResponseField>

<ResponseField name="Debug" type="bool">
  A flag to enable debug mode for the model. When enabled, Modus automatically
  logs the full request and response data to the console. Implementations can
  also use this flag to enable additional debug logging. Defaults to `false`.
</ResponseField>

<ResponseField name="Info()" type="method">
  Returns information about the model set by the Modus Runtime when creating the
  instance. See the [`ModelInfo`](#modelinfo) object for more information.
</ResponseField>

<ResponseField name="Invoke(input)" type="method">
  Invokes the model with input data and returns the output data.
</ResponseField>

#### ModelInfo

Information about a model that's used to construct a `Model` instance. It's also
available from a method on the `Model` interface.

<Info>
  This struct relays information from the Modus runtime to the model
  implementation. Generally, you don't need to create `ModelInfo` instances
  directly.

  However, if you are implementing a custom model, you may wish to use a field
  from this struct, such as `FullName`, for model providers that require the model
  name in the input request body.
</Info>

```go
type ModelInfo struct {
  Name string
  FullName string
}
```

<ResponseField name="Name" type="string">
  The name of the model from the app manifest.
</ResponseField>

<ResponseField name="FullName" type="string">
  The full name or identifier of the model, as defined by the model provider.
</ResponseField>


# MySQL APIs
Source: https://docs.hypermode.com/modus/sdk/go/mysql

Execute queries against a MySQL database

export const SdkHeader = ({language, feature}) => <Note>
    <p>
      While each Modus SDK offers similar capabilities, the APIs and usage may
      vary between languages.
    </p>
    <p>
      Modus {feature} APIs documentation is available on the following pages:
    </p>
    <ul>
      {(() => {
  const languages = ["AssemblyScript", "Go"];
  const page = feature.toLowerCase().replace(/\W/g, "");
  return languages.map(lang => {
    if (lang === language) {
      return <li>
                <b>
                  {lang} {feature} APIs
                </b>{" "}
                (this page)
              </li>;
    } else {
      return <li>
                <a href={`../${lang.toLowerCase()}/${page}`}>
                  {lang} {feature} APIs
                </a>
              </li>;
    }
  });
})()}
    </ul>
  </Note>;

<SdkHeader language="Go" feature="MySQL" />

The Modus MySQL APIs allow you to run queries against MySQL or any
MySQL-compatible database platform.

## Import

To begin, import the `mysql` package from the SDK:

```go
import "github.com/hypermodeinc/modus/sdk/go/pkg/mysql"
```

## MySQL APIs

{/* vale Google.Headings = NO */}

The APIs in the `mysql` package are below, organized by category.

<Tip>
  We're constantly introducing new APIs through ongoing development with early
  users. Please [open an issue](https://github.com/hypermodeinc/modus/issues) if
  you have ideas on what would make Modus even more powerful for your next app!
</Tip>

### Functions

#### Execute

Execute a SQL statement against a MySQL database, without any data returned. Use
this for insert, update, or delete operations, or for other SQL statements that
don't return data.

<Note>
  The `Execute` function is for operations that don't return data. However, some
  insert/update/delete operations may still return data. In these cases, you can
  use the `QueryScalar` or `Query` functions instead.
</Note>

```go
func Execute(connection, statement string, params ...any) (*db.Response, error)
```

<ResponseField name="connection" type="string" required>
  Name of the connection, as [defined in the
  manifest](/modus/app-manifest#connections).
</ResponseField>

<ResponseField name="statement" type="string" required>
  SQL statement containing the query or mutation operation to execute.

  <Warning>
    While it's possible to directly include parameter values into your SQL
    statement, it's highly recommended to pass parameters as arguments instead.
    This can help to protect injection attacks and other security vulnerabilities.
  </Warning>
</ResponseField>

<ResponseField name="params" type="...any">
  Optional parameters to include with the query.
</ResponseField>

#### Query

Execute a SQL statement against a MySQL database, returning a set of rows. In
the results, each row converts to an object of type `T`, with fields matching
the column names.

```go
func Query[T any](connection, statement string, params ...any) (*db.QueryResponse[T], error)
```

<ResponseField name="T" required>
  Type of object to use for the data returned from the query. This can be any
  type, including a custom type defined in your project. It should match the shape
  of the row returned from the SQL query.

  <Tip>
    Define custom types in the project's source code. All types must be JSON
    serializable. You can also use built-in types such as strings, numbers, slices,
    and maps.

    If working with MySQL's `point` data type, you can use a [`Point`](#point) or
    [`Location`](#location) object to represent the data.
  </Tip>
</ResponseField>

<ResponseField name="connection" type="string" required>
  Name of the connection, as [defined in the
  manifest](/modus/app-manifest#connections).
</ResponseField>

<ResponseField name="statement" type="string" required>
  SQL statement containing the query or mutation operation to execute.

  <Warning>
    While it's possible to directly include parameter values into your SQL
    statement, it's highly recommended to pass parameters as arguments instead.
    This can help to protect injection attacks and other security vulnerabilities.
  </Warning>
</ResponseField>

<ResponseField name="params" type="...any">
  Optional parameters to include with the query.
</ResponseField>

#### QueryScalar

Execute a SQL statement against a MySQL database, returning a single scalar
value. For example, the result could be a count, sum, or average, or it could be
an identifier.

```go
func QueryScalar[T any](connection, statement string, params ...any) (*db.ScalarResponse[T], error)
```

<ResponseField name="T" required>
  Type of object to use for the data returned from the query. This should
  generally be a scalar data type, such as a number or string. It should match
  the type of the data returned from the SQL query.
</ResponseField>

<ResponseField name="connection" type="string" required>
  Name of the connection, as [defined in the
  manifest](/modus/app-manifest#connections).
</ResponseField>

<ResponseField name="statement" type="string" required>
  SQL statement containing the query or mutation operation to execute.

  <Warning>
    While it's possible to directly include parameter values into your SQL
    statement, it's highly recommended to pass parameters as arguments instead.
    This can help to protect injection attacks and other security vulnerabilities.
  </Warning>
</ResponseField>

<ResponseField name="params" type="...any">
  Optional parameters to include with the query.
</ResponseField>

### Types

#### Location

Represents a location on Earth, having `Longitude` and `Latitude` coordinates.

Correctly serializes to and from MySQL's point type, in (longitude, latitude)
order.

<Info>
  This struct is identical to the [Point](#point) struct, but uses different
  field names.
</Info>

```go
type Location struct {
  Longitude float64
  Latitude float64
}
```

<ResponseField name="Longitude" type="float64" required>
  The longitude coordinate of the location, in degrees.
</ResponseField>

<ResponseField name="Latitude" type="float64" required>
  The latitude coordinate of the location, in degrees.
</ResponseField>

#### Point

Represents a point in 2D space, having `X` and `Y` coordinates. Correctly
serializes to and from MySQL's point type, in (x, y) order.

<Info>
  This struct is identical to the [Location](#location) struct, but uses
  different field names.
</Info>

```go
type Point struct {
  X float64
  Y float64
}
```

<ResponseField name="X" type="float64" required>
  The X coordinate of the point.
</ResponseField>

<ResponseField name="Y" type="float64" required>
  The Y coordinate of the point.
</ResponseField>

#### QueryResponse

Represents the response from a [`Query`](#query) operation.

```go
type QueryResponse[T any] struct {
  RowsAffected uint32
  LastInsertId uint64
  Rows []T
}
```

<ResponseField name="RowsAffected" type="uint32">
  The number of rows affected by the operation, which typically corresponds to
  the number of rows returned.
</ResponseField>

<ResponseField name="lastInsertId" type="uint64">
  When inserting a row, this field contains the ID of the last inserted row.
  This is useful for tables with auto-incrementing primary keys.
</ResponseField>

<ResponseField name="Rows" type="[]T">
  An slice of objects, each representing a row returned from the query. Each
  object has fields corresponding to the columns in the result set.
</ResponseField>

#### Response

Represents the response from an [`Execute`](#execute) operation.

```go
type Response struct {
  RowsAffected uint32
  LastInsertId uint64
}
```

<ResponseField name="RowsAffected" type="uint32">
  The number of rows affected by the operation, which typically corresponds to
  the number of rows returned.
</ResponseField>

<ResponseField name="lastInsertId" type="uint64">
  When inserting a row, this field contains the ID of the last inserted row.
  This is useful for tables with auto-incrementing primary keys.
</ResponseField>

#### ScalarResponse

Represents the response from a [`QueryScalar`](#queryscalar) operation.

```go
type ScalarResponse[T any] struct {
  RowsAffected uint32
  LastInsertId uint64
  Value T
}
```

<ResponseField name="RowsAffected" type="uint32">
  The number of rows affected by the operation, which typically corresponds to
  the number of rows returned.
</ResponseField>

<ResponseField name="lastInsertId" type="uint64">
  When inserting a row, this field contains the ID of the last inserted row.
  This is useful for tables with auto-incrementing primary keys.
</ResponseField>

<ResponseField name="Value" type="T">
  The scalar value returned from the query.
</ResponseField>


# Neo4j APIs
Source: https://docs.hypermode.com/modus/sdk/go/neo4j

Execute queries and mutations against a Neo4j database

export const SdkHeader = ({language, feature}) => <Note>
    <p>
      While each Modus SDK offers similar capabilities, the APIs and usage may
      vary between languages.
    </p>
    <p>
      Modus {feature} APIs documentation is available on the following pages:
    </p>
    <ul>
      {(() => {
  const languages = ["AssemblyScript", "Go"];
  const page = feature.toLowerCase().replace(/\W/g, "");
  return languages.map(lang => {
    if (lang === language) {
      return <li>
                <b>
                  {lang} {feature} APIs
                </b>{" "}
                (this page)
              </li>;
    } else {
      return <li>
                <a href={`../${lang.toLowerCase()}/${page}`}>
                  {lang} {feature} APIs
                </a>
              </li>;
    }
  });
})()}
    </ul>
  </Note>;

<SdkHeader language="Go" feature="Neo4j" />

The Modus Neo4j APIs allow you to run queries and mutations against a Neo4j
database.

## Import

To begin, import the `neo4j` package from the SDK:

```go
import "github.com/hypermodeinc/modus/sdk/go/pkg/neo4j"
```

## Neo4j APIs

{/* vale Google.Headings = NO */}

The APIs in the `neo4j` package are below, organized by category.

<Tip>
  We're constantly introducing new APIs through ongoing development with early
  users. Please [open an issue](https://github.com/hypermodeinc/modus/issues) if
  you have ideas on what would make Modus even more powerful for your next app!
</Tip>

### Functions

#### ExecuteQuery

Executes a Cypher query on the Neo4j database.

```go
func ExecuteQuery(
  connection,
  query string,
  parameters map[string]any,
  opts ...Neo4jOption
) (*EagerResult, error)
```

<ResponseField name="connection" type="string" required>
  Name of the connection, as [defined in the
  manifest](/modus/app-manifest#connections).
</ResponseField>

<ResponseField name="query" type="string" required>
  A Neo4j Cypher query to execute.
</ResponseField>

<ResponseField name="parameters" type="map[string]any" required>
  A map of parameters to pass to the query.
</ResponseField>

<ResponseField name="opts" type="Neo4jOption">
  Optional arguments to pass to the query. Specify the database name using the
  `WithDbName` option.
</ResponseField>

#### GetProperty

Get a property from an entity at a given key and cast or decode it to a specific
type.

```go
func GetProperty[T PropertyValue](e Entity, key string) (T, error)
```

<ResponseField name="T" type="PropertyValue" required>
  The type to cast or decode the value to.
</ResponseField>

<ResponseField name="e" type="Entity" required>
  The entity to get the value from.
</ResponseField>

<ResponseField name="key" type="string" required>
  The key of the value to get.
</ResponseField>

#### GetRecordValue

Get a value from a record at a given key and cast or decode it to a specific
type.

```go
func GetRecordValue[T RecordValue](record *Record, key string) (T, error)
```

<ResponseField name="T" type="RecordValue" required>
  The type to cast or decode the value to.
</ResponseField>

<ResponseField name="record" type="*Record" required>
  The record to get the value from.
</ResponseField>

<ResponseField name="key" type="string" required>
  The key of the value to get.
</ResponseField>

### Types

#### EagerResult

The result of a Neo4j query or mutation.

```go
type EagerResult struct {
  Keys    []string
  Records []*Record
}
```

<ResponseField name="Keys" type="[]string">
  The keys of the result.
</ResponseField>

<ResponseField name="Records" type="[]*Record">
  The records of the result.
</ResponseField>

#### Entity

An interface representing possible entities in a Neo4j query result.

```go
type Entity interface {
  GetElementId() string
  GetProperties() map[string]any
}
```

<ResponseField name="GetElementId()" type="method">
  Returns the ID of the entity.
</ResponseField>

<ResponseField name="GetProperties()" type="method">
  Returns the properties of the entity.
</ResponseField>

#### Node

A node in a Neo4j query result.

```go
type Node struct {
  ElementId string
  Labels    []string
  Props     map[string]any
}
```

<ResponseField name="ElementId" type="string">
  The ID of the node.
</ResponseField>

<ResponseField name="Labels" type="[]string">
  The labels of the node.
</ResponseField>

<ResponseField name="Props" type="map[string]any">
  The properties of the node.
</ResponseField>

<ResponseField name="GetElementId()" type="method">
  Returns the ID of the node.
</ResponseField>

<ResponseField name="GetProperties()" type="method">
  Returns the properties of the node.
</ResponseField>

#### Path

A path in a Neo4j query result.

```go
type Path struct {
  Nodes         []Node
  Relationships []Relationship
}
```

<ResponseField name="Nodes" type="[]Node">
  The nodes in the path.
</ResponseField>

<ResponseField name="Relationships" type="[]Relationship">
  The relationships in the path.
</ResponseField>

#### Point2D

A 2D point in a Neo4j query result.

```go
type Point2D struct {
  X            float64
  Y            float64
  SpatialRefId uint32
}
```

<ResponseField name="X" type="float64">
  The X coordinate of the point.
</ResponseField>

<ResponseField name="Y" type="float64">
  The Y coordinate of the point.
</ResponseField>

<ResponseField name="SpatialRefId" type="uint32">
  The spatial reference ID of the point.
</ResponseField>

#### Point3D

A 3D point in a Neo4j query result.

```go
type Point3D struct {
  X            float64
  Y            float64
  Z            float64
  SpatialRefId uint32
}
```

<ResponseField name="X" type="float64">
  The X coordinate of the point.
</ResponseField>

<ResponseField name="Y" type="float64">
  The Y coordinate of the point.
</ResponseField>

<ResponseField name="Z" type="float64">
  The Z coordinate of the point.
</ResponseField>

<ResponseField name="SpatialRefId" type="uint32">
  The spatial reference ID of the point.
</ResponseField>

#### PropertyValue

A type constraint for retrieving property values from a Neo4j entity.

```go
type PropertyValue interface {
  bool | int64 | float64 | string |
    time.Time | []byte | []any | Point2D | Point3D
}
```

#### Record

A record in a Neo4j query result.

```go
type Record struct {
  Keys   []string
  Values []string
}
```

<ResponseField name="Values" type="[]string">
  The values of the record.
</ResponseField>

<ResponseField name="Keys" type="[]string">
  The keys of the record.
</ResponseField>

<ResponseField name="Get(key)" type="method">
  Get the value of a record at a given key as a JSON encoded string.

  <Info>
    Usually, you should use the `GetRecordValue[T](key)` function instead of this method.
  </Info>
</ResponseField>

<ResponseField name="AsMap()" type="method">
  Convert the record to a map of keys and JSON encoded string values.
</ResponseField>

#### RecordValue

A type constraint for retrieving values from a Neo4j record.

```go
type RecordValue interface {
  bool | int64 | float64 | string | time.Time |
  []byte | []any | map[string]any |
  Node | Relationship | Path | Point2D | Point3D
}
```

#### Relationship

A relationship in a Neo4j query result.

```go
type Relationship struct {
  ElementId      string
  StartElementId string
  EndElementId   string
  Type           string
  Props          map[string]any
}
```

<ResponseField name="ElementId" type="string">
  The ID of the relationship.
</ResponseField>

<ResponseField name="StartElementId" type="string">
  The ID of the start node.
</ResponseField>

<ResponseField name="EndElementId" type="string">
  The ID of the end node.
</ResponseField>

<ResponseField name="Type" type="string">
  The type of the relationship.
</ResponseField>

<ResponseField name="Props" type="map[string]any">
  The properties of the relationship.
</ResponseField>

<ResponseField name="GetElementId()" type="method">
  Returns the ID of the node.
</ResponseField>

<ResponseField name="GetProperties()" type="method">
  Returns the properties of the node.
</ResponseField>


# Modus Go SDK
Source: https://docs.hypermode.com/modus/sdk/go/overview

Learn how to use the Modus Go SDK

export const language_0 = "Go"

The Modus {language_0} SDK provides a set of APIs that allow you to interact with
various databases and services in Modus apps written in {language_0}. It's
designed to work seamlessly with the Modus platform, enabling you to build
powerful applications with ease.

<Info>
  The Modus SDKs come in multiple languages, each following the conventions for
  that language, including its capabilities and limitations. While each SDK
  provides similar features, the APIs may differ slightly between languages. Be
  sure to refer to the documentation for the specific SDK you're using.

  Wherever possible, we've tried to keep the APIs consistent across languages.
  However, you may find differences in the APIs due to language-specific
  constraints.

  If you have any questions or need help, please reach out to us via the `#modus`
  channel on the [Hypermode Discord server](https://discord.hypermode.com/).
</Info>

## Importing the APIs

The Modus Go SDK organizes its APIs into packages based on their purpose. In
your Go code, you can import each package you'd like to use like this:

```go
import "github.com/hypermodeinc/modus/sdk/go/pkg/<package>"
```

## Available APIs

<Tip>
  We're constantly introducing new APIs through ongoing development with early
  users. Please [open an issue](https://github.com/hypermodeinc/modus/issues) if
  you have ideas on what would make Modus even more powerful for your next app!
</Tip>

The following packages are available. They're grouped into categories below for
your convenience. Click on a package to view more information about its APIs.

### Client APIs

| Package                | Purpose                                                                            |
| :--------------------- | :--------------------------------------------------------------------------------- |
| [`http`](./http)       | Provides access to external HTTP endpoints, including REST APIs and other services |
| [`graphql`](./graphql) | Allows you to securely call and fetch data from any GraphQL endpoint               |

### Database APIs

| Package                      | Purpose                                         |
| :--------------------------- | :---------------------------------------------- |
| [`dgraph`](./dgraph)         | Access and modify data in a Dgraph database     |
| [`mysql`](./mysql)           | Access and modify data in a MySQL database      |
| [`neo4j`](./neo4j)           | Access and modify data in a Neo4j database      |
| [`postgresql`](./postgresql) | Access and modify data in a PostgreSQL database |

### Inference APIs

| Package              | Purpose                                                                                        |
| :------------------- | :--------------------------------------------------------------------------------------------- |
| [`models`](./models) | Invoke AI models, including large language models, embedding models, and classification models |

### Storage APIs

| Package                        | Purpose                                                    |
| :----------------------------- | :--------------------------------------------------------- |
| [`collections`](./collections) | Provides integrated storage and vector search capabilities |

### System APIs

| Package                    | Purpose                                                  |
| :------------------------- | :------------------------------------------------------- |
| [`console`](./console)     | Provides logging, assertion, and timing functions        |
| [`localtime`](./localtime) | Allows you to access the user's local time and time zone |


# PostgreSQL APIs
Source: https://docs.hypermode.com/modus/sdk/go/postgresql

Execute queries against a PostgreSQL database

export const SdkHeader = ({language, feature}) => <Note>
    <p>
      While each Modus SDK offers similar capabilities, the APIs and usage may
      vary between languages.
    </p>
    <p>
      Modus {feature} APIs documentation is available on the following pages:
    </p>
    <ul>
      {(() => {
  const languages = ["AssemblyScript", "Go"];
  const page = feature.toLowerCase().replace(/\W/g, "");
  return languages.map(lang => {
    if (lang === language) {
      return <li>
                <b>
                  {lang} {feature} APIs
                </b>{" "}
                (this page)
              </li>;
    } else {
      return <li>
                <a href={`../${lang.toLowerCase()}/${page}`}>
                  {lang} {feature} APIs
                </a>
              </li>;
    }
  });
})()}
    </ul>
  </Note>;

<SdkHeader language="Go" feature="PostgreSQL" />

The Modus PostgreSQL APIs allow you to run queries against PostgreSQL or any
PostgreSQL-compatible database platform.

## Import

To begin, import the `postgresql` package from the SDK:

```go
import "github.com/hypermodeinc/modus/sdk/go/pkg/postgresql"
```

## PostgreSQL APIs

{/* vale Google.Headings = NO */}

The APIs in the `postgresql` package are below, organized by category.

<Tip>
  We're constantly introducing new APIs through ongoing development with early
  users. Please [open an issue](https://github.com/hypermodeinc/modus/issues) if
  you have ideas on what would make Modus even more powerful for your next app!
</Tip>

### Functions

#### Execute

Execute a SQL statement against a PostgreSQL database, without any data
returned. Use this for insert, update, or delete operations, or for other SQL
statements that don't return data.

<Note>
  The `Execute` function is for operations that don't return data. However, some
  insert/update/delete operations may still return data. In these cases, you can
  use the `QueryScalar` or `Query` functions instead.
</Note>

```go
func Execute(connection, statement string, params ...any) (*db.Response, error)
```

<ResponseField name="connection" type="string" required>
  Name of the connection, as [defined in the
  manifest](/modus/app-manifest#connections).
</ResponseField>

<ResponseField name="statement" type="string" required>
  SQL statement containing the query or mutation operation to execute.

  <Warning>
    While it's possible to directly include parameter values into your SQL
    statement, it's highly recommended to pass parameters as arguments instead.
    This can help to protect injection attacks and other security vulnerabilities.
  </Warning>
</ResponseField>

<ResponseField name="params" type="...any">
  Optional parameters to include with the query.
</ResponseField>

#### Query

Execute a SQL statement against a PostgreSQL database, returning a set of rows.
In the results, each row converts to an object of type `T`, with fields matching
the column names.

```go
func Query[T any](connection, statement string, params ...any) (*db.QueryResponse[T], error)
```

<ResponseField name="T" required>
  Type of object to use for the data returned from the query. This can be any
  type, including a custom type defined in your project. It should match the shape
  of the row returned from the SQL query.

  <Tip>
    Define custom types in the project's source code. All types must be JSON
    serializable. You can also use built-in types such as strings, numbers, slices,
    and maps.

    If working with PostgreSQL's `point` data type, you can use a [`Point`](#point)
    or [`Location`](#location) object to represent the data.
  </Tip>
</ResponseField>

<ResponseField name="connection" type="string" required>
  Name of the connection, as [defined in the
  manifest](/modus/app-manifest#connections).
</ResponseField>

<ResponseField name="statement" type="string" required>
  SQL statement containing the query or mutation operation to execute.

  <Warning>
    While it's possible to directly include parameter values into your SQL
    statement, it's highly recommended to pass parameters as arguments instead.
    This can help to protect injection attacks and other security vulnerabilities.
  </Warning>
</ResponseField>

<ResponseField name="params" type="...any">
  Optional parameters to include with the query.
</ResponseField>

#### QueryScalar

Execute a SQL statement against a PostgreSQL database, returning a single scalar
value. For example, the result could be a count, sum, or average, or it could be
an identifier.

```go
func QueryScalar[T any](connection, statement string, params ...any) (*db.ScalarResponse[T], error)
```

<ResponseField name="T" required>
  Type of object to use for the data returned from the query. This should
  generally be a scalar data type, such as a number or string. It should match
  the type of the data returned from the SQL query.
</ResponseField>

<ResponseField name="connection" type="string" required>
  Name of the connection, as [defined in the
  manifest](/modus/app-manifest#connections).
</ResponseField>

<ResponseField name="statement" type="string" required>
  SQL statement containing the query or mutation operation to execute.

  <Warning>
    While it's possible to directly include parameter values into your SQL
    statement, it's highly recommended to pass parameters as arguments instead.
    This can help to protect injection attacks and other security vulnerabilities.
  </Warning>
</ResponseField>

<ResponseField name="params" type="...any">
  Optional parameters to include with the query.
</ResponseField>

### Types

#### Location

Represents a location on Earth, having `Longitude` and `Latitude` coordinates.

Correctly serializes to and from PostgreSQL's point type, in (longitude,
latitude) order.

<Info>
  This struct is identical to the [Point](#point) struct, but uses different
  field names.
</Info>

```go
type Location struct {
  Longitude float64
  Latitude float64
}
```

<ResponseField name="Longitude" type="float64" required>
  The longitude coordinate of the location, in degrees.
</ResponseField>

<ResponseField name="Latitude" type="float64" required>
  The latitude coordinate of the location, in degrees.
</ResponseField>

#### Point

Represents a point in 2D space, having `X` and `Y` coordinates. Correctly
serializes to and from PostgreSQL's point type, in (x, y) order.

<Info>
  This struct is identical to the [Location](#location) struct, but uses
  different field names.
</Info>

```go
type Point struct {
  X float64
  Y float64
}
```

<ResponseField name="X" type="float64" required>
  The X coordinate of the point.
</ResponseField>

<ResponseField name="Y" type="float64" required>
  The Y coordinate of the point.
</ResponseField>

#### QueryResponse

Represents the response from a [`Query`](#query) operation.

```go
type QueryResponse[T any] struct {
  RowsAffected uint32
  LastInsertId uint64
  Rows []T
}
```

<ResponseField name="RowsAffected" type="uint32">
  The number of rows affected by the operation, which typically corresponds to
  the number of rows returned.
</ResponseField>

<ResponseField name="LastInsertId" type="uint64">
  This field is available for other database types, but isn't populated for
  PostgreSQL. Instead, use `Query` or `QueryScalar` with a `RETURNING` clause to
  get the last inserted ID.
</ResponseField>

<ResponseField name="Rows" type="[]T">
  An slice of objects, each representing a row returned from the query. Each
  object has fields corresponding to the columns in the result set.
</ResponseField>

#### Response

Represents the response from an [`Execute`](#execute) operation.

```go
type Response struct {
  RowsAffected uint32
  LastInsertId uint64
}
```

<ResponseField name="RowsAffected" type="uint32">
  The number of rows affected by the operation, which typically corresponds to
  the number of rows returned.
</ResponseField>

<ResponseField name="LastInsertId" type="uint64">
  This field is available for other database types, but isn't populated for
  PostgreSQL. Instead, use `Query` or `QueryScalar` with a `RETURNING` clause to
  get the last inserted ID.
</ResponseField>

#### ScalarResponse

Represents the response from a [`QueryScalar`](#queryscalar) operation.

```go
type ScalarResponse[T any] struct {
  RowsAffected uint32
  LastInsertId uint64
  Value T
}
```

<ResponseField name="RowsAffected" type="uint32">
  The number of rows affected by the operation, which typically corresponds to
  the number of rows returned.
</ResponseField>

<ResponseField name="LastInsertId" type="uint64">
  This field is available for other database types, but isn't populated for
  PostgreSQL. Instead, use `Query` or `QueryScalar` with a `RETURNING` clause to
  get the last inserted ID.
</ResponseField>

<ResponseField name="Value" type="T">
  The scalar value returned from the query.
</ResponseField>


# Search
Source: https://docs.hypermode.com/modus/search

Add natural language search to your app using AI embeddings

The Modus Collections API provides a robust way to store, retrieve, and search
through data using both natural language and vector-based search methods. By
leveraging embeddings, developers can enable semantic and similarity-based
searches, improving the relevance of search results within their applications.

For example, with natural language similarity, if you search for a product
description like 'sleek red sports car', the search method returns similar
product descriptions such as "luxury sports car in red" or 'high-speed car with
sleek design'.

## Understanding key components

**Collections**: a collection is a structured storage that organizes and stores
textual data and associated metadata. Collections enable sophisticated search,
retrieval, and classification tasks using vector embeddings.

**Search Methods**: a search method associated with a collection, defines how to
convert collection items into a vector representation and provides indexing
parameters.

**Vector embeddings**: for vector-based search and comparison, Modus converts
each item in the collection into a vector representation called **embedding**.
By embedding data, you enable powerful natural language and similarity-based
searches.

<Note>
  Modus runtime automatically compute the embeddings, according to your
  configuration, when you add or update items.
</Note>

## Initializing your collection

Before implementing search, ensure you have
[defined a collection in the app manifest](./app-manifest#collections). In this
example, `myProducts` is the collection used to store product descriptions.

First, we need to populate the collection with items (for example, product
descriptions). You can insert individual or multiple items using the `upsert`
and `upsertBatch` methods, respectively.

Use `upsert` to insert a product description into the collection. If you don't
specify a key, Modus generates a unique key for you.

<CodeGroup>
  ```go Go
  func AddProduct(description string) ([]string, error) {
    res, err := collections.Upsert(
      "myProducts",  // Collection name defined in the manifest
      nil,           // using nil to let Modus generate a unique ID
      description,   // the text to store
      nil            // we don't have labels for this item
      )
    if err != nil {
      return nil, err
    }
    return res.Keys, nil
  }
  ```

  ```ts AssemblyScript
  export function addProduct(description: string): string {
    const response = collections.upsert(
      "myProducts", // Collection name defined in the manifest
      null, // using null to let Modus generate a unique ID
      description, // the text to store
      // no labels for this item
      // no namespace provided, use defautl namespace
    )
    return response.keys[0] // return the identifier of the item
  }
  ```
</CodeGroup>

## Configure your search method

The search capability relies on a search method and embedding function. To
configure your search method.

### Create an embedding function

An embedding function is any API function that transforms text into vectors that
represent their meaning in a high-dimensional space.

Embeddings functions must have the following signature:

<CodeGroup>
  ```go Go
  package main

  func Embed(text []string) ([][]float32, error) {
    ...
  }

  ```

  ```ts AssemblyScript
  export function embed(text: string[]): f32[][] {
    ...
  }
  ```
</CodeGroup>

Modus computes vectors using embedding models. Here are a few examples:

<Tabs>
  <Tab title="all-MiniLM-L6-v2">
    [Declare the model](./app-manifest#models) in the app manifest

    ```json model.json
      "models": {
        // model card: https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2
        "minilm": {
          "sourceModel": "sentence-transformers/all-MiniLM-L6-v2", // model name on the provider
          "provider": "hugging-face", // provider for this model
          "connection": "hypermode" // host where the model is running
        }
      }
    ```

    Create the embedding function using the embedding model:

    <CodeGroup>
      ```go Go
      package main

      import (
      "github.com/hypermodeAI/functions-go/pkg/models"
      "github.com/hypermodeAI/functions-go/pkg/models/experimental"
      )

      func Embed(text []string) ([][]float32, error) {
        // "minilm" is the model name declared in the application manifest
        model, err := models.GetModel[experimental.EmbeddingsModel]("minilm")
        if err != nil {
            return nil, err
        }

        input, err := model.CreateInput(text...)
        if err != nil {
            return nil, err
        }
        output, err := model.Invoke(input)
        if err != nil {
            return nil, err
        }
        return output.Predictions, nil
      }

      ```

      ```ts AssemblyScript
      import { models } from "@hypermode/modus-sdk-as"
      import { EmbeddingsModel } from "@hypermode/modus-sdk-as/models/experimental/embeddings"

      export function embed(texts: string[]): f32[][] {
        // "minilm" is the model name declared in the application manifest
        const model = models.getModel<EmbeddingsModel>("minilm")
        const input = model.createInput(texts)
        const output = model.invoke(input)
        return output.predictions
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="OpenAI">
    [Declare the model](./app-manifest#models) in the app manifest

    ```json modus.json
      "models": {
        // model docs: https://platform.openai.com/docs/models/embeddings
        "openai-embeddings": {
          "sourceModel": "text-embedding-3-small",
          "connection": "openai",
          "path": "v1/embeddings"
        }
      },
      "connections": {
        "openai": {
          "type": "http",
          "baseUrl": "https://api.openai.com/",
          "headers": {
            "Authorization": "Bearer {{API_KEY}}"
          }
        }
      }
    ```

    Create the embedding function using the embedding model:

    <CodeGroup>
      ```go Go
      import (
        "github.com/hypermodeAI/functions-go/pkg/models"
        "github.com/hypermodeAI/functions-go/pkg/models/experimental"
      )

      func Embed(texts ...string) ([][]float32, error) {
        // retrieve the model for OpenAI embeddings
        // "openai-embeddings" is the model name declared in the app manifest
        model, err := models.GetModel[openai.EmbeddingsModel]("openai-embeddings")
        if err != nil {
          return nil, fmt.Errorf("failed to get OpenAI embeddings model: %w", err)
        }

        // create input for the model using the provided texts
        input, err := model.CreateInput(texts)
        if err != nil {
          return nil, fmt.Errorf("failed to create input for OpenAI embeddings: %w", err)
        }

        // invoke the model with the generated input
        output, err := model.Invoke(input)
        if err != nil {
          return nil, fmt.Errorf("failed to invoke OpenAI embeddings model: %w", err)
        }

        // prepare the result slice based on the size of the output data
        results := make([][]float32, len(output.Data))

        // copy embeddings from output into the result slice
        for i, d := range output.Data {
          results[i] = d.Embedding
        }

        return results, nil
      }
      ```

      ```ts AssemblyScript
      export function embed(text: string[]): f32[][] {
        const model = models.getModel<OpenAIEmbeddingsModel>("openai-embeddings")
        // "openai-embeddings" is the model name declared in the app manifest
        const input = model.createInput(text)
        const output = model.invoke(input)
        return output.data.map<f32[]>((d) => d.embedding)
      }
      ```
    </CodeGroup>
  </Tab>
</Tabs>

### Declare the search method

With an embedding function in place, declare a search method in the
[collection properties](/modus/app-manifest#collections).

```json modus.json
  "collections": {
    "myProducts": {
        "searchMethods": {
            "searchMethod1": {
                "embedder": "embed" // embedding function name
            }
        }
    }
  }

```

## Implement semantic similarity search

With the products stored, you can now search the collection by semantic
similarity. The search] API computes an embedding for the provided text,
compares it with the embeddings of the items in the collection, and returns the
most similar items.

<CodeGroup>
  ```go Go
  func SearchProducts(productDescription string, maxItems int) (*collections.CollectionSearchResult, error) {
    return collections.Search(myProducts, searchMethods[0], productDescription, collections.WithLimit(maxItems), collections.WithReturnText(true))
  }
  ```

  ```ts AssemblyScript
  export function searchProducts(
    product_description: string,
    maxItems: i32,
  ): collections.CollectionSearchResult {
    const response = collections.search(
      "myProducts", // collection name declared in the application manifest
      "searchMethod1", // search method declared for this collection in the manifest
      product_description, // text to search for
      maxItems,
      true, //  returnText: bool, true to return the items text.
      // no namespace provide, use the default namespace
    )
    return response
  }
  ```
</CodeGroup>

### Search result format

The search response is a CollectionSearchResult containing the following fields:

* `collection`: the name of the collection.
* `status`: the status of the operation.
* `objects`: the search result items with their text, distance, and score
  values.
  * `distance`: a lower value indicates a closer match between the search query
    and the item in the collection
  * `score`: a higher value (closer to 1) represents a better match

```json
{
  "collection": "myProducts",
  "status": "success",
  "objects": [
    {
      "key": "item-key-123",
      "text": "Sample product description",
      "distance": 0.05,
      "score": 0.95
    }
  ]
}
```

## Search for similar Items

When you need to search similar items to a given item, use the `searchByVector`
API. Retrieve the vector associated with the given item by its key, then perform
a search using that vector.

<CodeGroup>
  ```go Go
  func SearchSimilarProduct(productKey string, maxItems int) (*collections.CollectionSearchResult, error) {
    vec, err := collections.GetVector(
      "myProducts",
      "searchMethod1",
      productKey)

    if err != nil {
      return nil, err
    }
    return collections.SearchByVector(
      "myProducts",
      "searchMethod1",
      vec,
      collections.WithLimit(maxItems),
      collections.WithReturnText(true)
    )
  }
  ```

  ```ts AssemblyScript
  export function searchSimilarProducts(
    productId: string,
    maxItems: i32,
  ): collections.CollectionSearchResult {
    const embedding_vector = collections.getVector(
      "myProducts", // Collection name defined in the manifest
      "searchMethod1", // search method declared for the collection
      productId, // key of the collection item to retrieve
    )
    // search for similar products using the embedding vector
    const response = collections.searchByVector(
      "myProducts",
      "searchMethod1",
      embedding_vector,
      maxItems,
      true, // get the product description
    )

    return response
  }
  ```
</CodeGroup>

## Develop locally with Collections

While Collections expose a key-value interface for working with data, a
PostgreSQL database instance persists the data. When using Collections in a
Modus app deployed to the Hypermode platform, Hypermode manages this PostgreSQL
database and users don't need to perform any additional setup. However, when
developing with Modus locally or outside of the Hypermode platform, you need a
PostgreSQL instance for the Collections persistence layer.

<Note>
  The dependency on PostgreSQL is temporary and we're working to replace it with
  ModusDB, an embedded multi-model database, in an upcoming release.
</Note>

Any hosting method for this PostgreSQL database is sufficient, so feel free to
use your favorite method of installing and running PostgreSQL locally or in the
cloud. You must apply a database migration after you start the PostgreSQL
database (Step 3 below) and set the `MODUS_DB` environment variable with your
PostgreSQL database connection string (Step 4 below). The steps below describe
using [Docker](https://www.docker.com/products/docker-desktop/) to start and
configure a PostgreSQL instance for local development with Collections.

To start and configure a local PostgreSQL instance for working with Collections
locally using [Docker Compose](https://docs.docker.com/compose/), follow these
steps:

<Steps>
  <Step title="Clone Modus locally">
    Clone the [Modus GitHub repository](https://github.com/hypermodeinc/modus):

    ```sh
    git clone https://github.com/hypermodeinc/modus.git
    ```
  </Step>

  <Step title="Start a PostgreSQL instance">
    Start the Collections PostgreSQL database using the local Docker Compose script:

    ```sh
    cd modus/runtime/tools/local
    docker compose up
    ```
  </Step>

  <Step title="Apply database migration">
    Next, apply the database schema using the
    [golang-migrate](https://github.com/golang-migrate/migrate) utility.

    On MacOS, you can install this utility with the following:

    ```sh
    brew install golang-migrate
    ```

    Then, you can apply the migration as follows:

    ```sh
    export POSTGRESQL_URL='postgresql://postgres:postgres@localhost:5433/my-runtime-db?sslmode=disable'
    migrate -database ${POSTGRESQL_URL} -path ../../db/migrations up
    ```
  </Step>

  <Step title="Set environment variable">
    Set the `MODUS_DB` environment variable:

    ```sh
    export MODUS_DB=postgresql://postgres:postgres@localhost:5433/my-runtime-db?sslmode=disable
    ```
  </Step>
</Steps>

You can now use Collections locally in your Modus app.


# Observe Functions
Source: https://docs.hypermode.com/observe-functions

Understand what's happening within your functions

When you invoke a function or model within your app, Modus records the
execution. The Hypermode Console makes debugging simple with easy to understand
logs and metrics.

## Function runs

From your project, navigate to the Function Runs tab to view execution logs of
your functions.

![function runs](https://mintlify.s3.us-west-1.amazonaws.com/hypermode/images/observe-functions/function-runs.png)

For more information on recording info, warnings, and errors in your Modus app,
see [Error Handling](/modus/error-handling).

## Model tracing

For each model invocation, Hypermode records the model inference and related
metadata. This includes the input and output of the model, as well as the
timestamp and duration of the inference.

From your project, select the Inferences tab to view the inferences from your
app's models.

![model tracing](https://mintlify.s3.us-west-1.amazonaws.com/hypermode/images/observe-functions/inference-history.png)


# Quickstart
Source: https://docs.hypermode.com/quickstart

Start building AI features in under five minutes

In this quickstart we'll show you how to get set up with Hypermode and build an
intelligent API that you can integrate into your app. You'll learn how to use
the basic components of a Modus app and how to deploy it to Hypermode.

## Prerequisites

* [Node.js](https://nodejs.org/en/download/package-manager) - v22 or higher
* Text editor - we recommend [VS Code](https://code.visualstudio.com/)
* Terminal - access Modus through a command-line interface (CLI)
* [GitHub Account](https://github.com/join)

## Deploying your first Hypermode project

<Steps>
  <Step title="Create Modus app">
    We built Hypermode on top of Modus, an open source, serverless framework for crafting
    intelligent functions and APIs, powered by WebAssembly. With Hypermode, you can deploy,
    secure, and observe your Modus apps.

    To get started, [create your first Modus app](/modus/quickstart). You can import this app into
    Hypermode in the next step.
  </Step>

  <Step title="Import Modus app">
    You can import your Modus app via the Hypermode Console or through the terminal with Hyp CLI.

    <Tabs>
      <Tab title="Hypermode Console">
        Navigate to the [Hypermode Console](https://hypermode.com/go) and click **New Project**.
        When prompted, connect your GitHub account and select the repository you want to import.
        Once you've selected your repository, click "Import" to deploy your app.
      </Tab>

      <Tab title="Hyp CLI">
        Install the Hyp CLI via npm.

        ```bash
        npm install -g @hypermode/hyp-cli
        ```

        From the terminal, run the following command to import your Modus app into Hypermode. This command
        will create your Hypermode project and deploy your app.

        ```bash
        hyp link
        ```
      </Tab>
    </Tabs>

    When Hypermode creates your project, a runtime is initiated for your app as well as connections to
    any [Hypermode-hosted models](/hosted-models).
  </Step>

  <Step title="Explore API endpoint">
    After deploying your app, Hypermode lands you in your project home. You can see the status of your
    project and the API endpoint generated for your app.

    From the **Query** page, you can run a sample query to verify it's working as expected. In the following
    query, we're going to use the `generateText` function to generate text from the shared Meta Llama
    3.1 model based on the prompt "How are black holes created?"

    ```GraphQL
    query myPrompt {
      generateText(text:"How are black holes created?")
    }
    ```

    <img className="block" src="https://mintlify.s3.us-west-1.amazonaws.com/hypermode/images/hyp-quickstart/graphiql-blackhole.png" alt="Hypermode's console showing results of query 'how are black holes created'." />
  </Step>

  <Step title="Observe function execution">
    Let's dig deeper into the behavior of our AI service when we ran the query by looking at the
    **Inferences** page. You can see the step-by-step inference process and the inputs and outputs of
    the model at each step of your function.
    After invoking the Meta Llama model from the function code, we can see the function execution. In this case, it took Llama 4.4 seconds to
    reply to the prompt. We can also see the parameters on both the inputs and outputs.

    ```json
    {
      "model": "meta-llama/Llama-3.2-3B-Instruct",
      "messages": [
        {
          "role": "system",
          "content": "You are a helpful assistant. Limit your answers to 150 words."
        },
        {
          "role": "user",
          "content": "How are black holes created?"
        }
      ],
      "max_tokens": 200,
      "temperature": 0.7
    }
    ```

    <img className="block" src="https://mintlify.s3.us-west-1.amazonaws.com/hypermode/images/hyp-quickstart/inference-history.png" alt="Hypermode's console showing the inputs and outputs of the last model inference." />
  </Step>

  <Step title="Customize your function">
    Hypermode makes it simple to iterate quickly. Let's make a few changes to your app
    to explore how easy customizing your API is.

    Our API is responding using language that is more formal than we want. Let's update our
    `generateText` function to respond using exclusively surfing analogies.

    <Tabs>
      <Tab title="Go">
        Go to the `main.go` file and locate the `generateText` function. Modify the function to only respond like a surfer, like this:

        ```ts main.go
        func GenerateText(text string) (string, error) {
          model, err := models.GetModel[openai.ChatModel]("text-generator")
          if err != nil {
              return "", err
          }

          input, err := model.CreateInput(
              openai.NewSystemMessage("You are a helpful assistant. Only respond using surfing analogies and metaphors."),
              openai.NewUserMessage(text),
          )
          if err != nil {
              return "", err
          }

          output, err := model.Invoke(input)
          if err != nil {
              return "", err
          }

          return strings.TrimSpace(output.Choices[0].Message.Content), nil
        }
        ```
      </Tab>

      <Tab title="AssemblyScript">
        Go to the `index.ts` file and locate the `generateText` function. Modify the function to only respond like a surfer, like this:

        ```ts index.ts
        export function generateText(text: string): string {
          const model = models.getModel<OpenAIChatModel>("text-generator")

          const input = model.createInput([
            new SystemMessage(
              "You are a helpful assistant. Only respond using surfing analogies and metaphors.",
            ),
            new UserMessage(text),
          ])

          const output = model.invoke(input)

          return output.choices[0].message.content.trim()
        }
        ```
      </Tab>
    </Tabs>

    Save the file and push an update to your Git repo. Hypermode automatically redeploys
    whenever you push an update to the target branch in your Git repo. Go back to the Hypermode Console
    and run the same query as before. You should see the response now uses surfing analogies!

    <img className="block" src="https://mintlify.s3.us-west-1.amazonaws.com/hypermode/images/hyp-quickstart/graphiql-surfing.png" alt="Hypermode's console showing results of new query." />
  </Step>
</Steps>

## Next steps

Hypermode and Modus provide a powerful platform for building and hosting AI
models, data, and logic. You now know the basics of Hypermode. There's no limit
to what you can build.

And when you're ready to [integrate Hypermode into your app](/integrate-api),
that's as simple as calling a GraphQL endpoint.


# Security
Source: https://docs.hypermode.com/security

Data handling, privacy, and security best practices

At Hypermode, we take security seriously. This document outlines our approach to
data handling, privacy, and security best practices to ensure your projects are
safe and secure.

## System description

Hypermode is a fully managed AI development platform that's designed to offer
easy integration of data and AI models, code-first inference definition, and
end-to-end visibility. The platform includes production hosting and
automatically created branch-based environments for both the Dgraph graph engine
and Modus function runtime.

Hypermode Inc. is responsible for the development and maintenance of the
service. Services leverage cloud-hosted infrastructure and we make some
components available as open source software under the Apache 2.0 License.
Relevant code repositories are available publicly through GitHub, and we welcome
contributions by the community, subject to a public code of conduct and GitHub
terms of service.

## Data handling and privacy

Hypermode maintains a strong commitment to protecting your data and privacy. For
detailed information on our data handling and privacy policies, please refer to
our [Privacy Policy](https://hypermode.com/privacy).

## Security best practices

Security is a shared responsibility. To help you keep your projects secure, we
recommend the following best practices:

* **Use strong passwords**: ensure that all user accounts use strong, unique
  passwords
* **Develop secure apps**: implement security and quality coding best practices
  in the code you write and deploy
* **Regularly update dependencies**: keep your project dependencies up-to-date
  to avoid vulnerabilities
* **Monitor for security alerts**: use tools to monitor your codebase for
  security vulnerabilities and address them promptly
* **Manage roles and permissions**: add and remove users from your organization
  as your team members change

## Reporting security issues

We take the security of Hypermode and our open source projects very seriously.
If you believe you have found a security vulnerability, we encourage you to let
us know right away.

We investigate all legitimate reports and do our best to quickly fix the
problem. Please report any issues or vulnerabilities via GitHub Security
Advisories instead of posting a public issue in GitHub. You can also send
security communications to [security@hypermode.com](mailto:security@hypermode.com).

Please include the version identifier and details on how the you can exploit the
vulnerability.

We appreciate your help in keeping Hypermode secure.


# Semantic Search With Dgraph and Modus
Source: https://docs.hypermode.com/semantic-search

Add natural language search to your app with Dgraph, Modus, and AI embeddings

By leveraging embeddings and similarity search backed by a scalable vector index
developers can enable semantic and similarity-based searches, improving the
relevance of search results within their applications. This tutorial covers
implementing semantic search using Modus, Dgraph, and Hypermode hosted AI models
to add natural language or semantic search to your app using an example of
ecommerce product data.

<iframe
  src="https://www.youtube.com/embed/Z2fB-nBf4Wo"
  title="Natural Language Search With Dgraph, Modus, and Hypermode"
  frameborder="0"
  allow="accelerometer; autoplay; clipboard-write;
encrypted-media; gyroscope; picture-in-picture"
  allowfullscreen
  style={{ aspectRatio: "16 / 9", width: "100%" }}
/>

## Semantic search overview

Semantic search focuses on understanding the meaning and context behind queries
rather than just matching keywords, using embeddings to capture semantic
relationships between concepts. Vector search serves as the technical
implementation method, converting text into numerical vector embeddings and
finding similar content through mathematical distance calculations in
multidimensional space.

Vector search is a powerful technique that transforms data (like text, images,
or audio) into numerical representations called embeddings. These embeddings
capture the semantic meaning of the content in a multi-dimensional space and
position similar items closer together. When performing a search, the query is
also converted into an embedding, and the system finds items whose embeddings
are closest to the query embedding.

This approach offers significant benefits over traditional keyword-based search,
including improved relevance by capturing context and semantics, enhanced
precision by understanding user intent, and the ability to handle complex
queries with higher accuracy. Vector search is particularly effective for
applications like semantic search, recommendation systems, and retrieval
augmented generation (RAG), optimizing both efficiency and accuracy in finding
and retrieving data based on meaningful similarity rather than exact matches.
When combined with graph traversals, vector search can enable complex GraphRAG
retrieval patterns.

## The components

* **Dgraph** is a scalable graph database capable of near real-time graph
  traversals and vector search.
* **Modus** is the serverless API framework for building AI applications.
* **Hypermode** is the platform for deploying AI applications, including model
  hosting.

## Prerequisites

This tutorial assumes you have:

1. Created a Dgraph instance, either hosted in the cloud or locally via Docker
   or installed via the Dgraph binary
2. Installed the Modus CLI and created a Modus app. See the
   [Modus Quickstart](modus/quickstart) to get started with Modus.

## Natural language search with Dgraph and Modus

The steps to implement natural language or semantic search with Dgraph include
defining the Dgraph connection in your Modus app manifest, selecting and
configuring an embedding model, declaring a vector index in the Dgraph DQL
schema, and using the `similar_to` DQL function to search for similar text in
vector space.

Our example app uses ecommerce product data consisting of product details to
enable semantic product search based on natural language terms.

## Declare Dgraph connection and Hypermode embedding model

First, update the Modus app manifest file `modus.json` to define the connection
to your Dgraph instance and the embedding model used to generate embeddings.
Here we're using the MiniLM model hosted by Hypermode and connecting to a
locally running Dgraph instance.

```json
{
  "$schema": "https://schema.hypermode.com/modus.json",
  "endpoints": {
    "default": {
      "type": "graphql",
      "path": "/graphql",
      "auth": "bearer-token"
    }
  },
  "models": {
    "minilm": {
      "sourceModel": "sentence-transformers/all-MiniLM-L6-v2",
      "connection": "hypermode",
      "provider": "hugging-face"
    }
  },
  "connections": {
    "dgraph-grpc": {
      "type": "dgraph",
      "grpcTarget": "localhost:9080"
    }
  }
}
```

<Note>
  In order to use Hypermode hosted models in the local Modus development
  environment you'll need to use the `hyp` CLI to connect your local environment
  with your Hypermode account. See the [Using Hypermode-hosted
  models](work-locally#using-hypermode-hosted-models) docs page for more
  information.
</Note>

## Type definitions

Next, in our Modus app we define our data model using classes with decorators
for automatic serialization/deserialization. The `@json` decorator enables JSON
serialization, while `@alias` maps property names to Dgraph convention friendly
formats.

We'll be using ecommerce data so we'll create simple types defining products and
their categories.

```ts
@json
export class Product {
  @alias("Product.id")
  id!: string

  @alias("Product.title")
  title: string = ""

  @alias("Product.description")
  description: string = ""

  @alias("Product.category")
  @omitnull()
  category: Category | null = null
}

@json
export class Category {
  @alias("Category.name")
  name: string = ""
}
```

## Embedding model integration

Next, we create an embedding function that uses a transformer model (MiniLM in
this case) to convert product descriptions and search queries into vectors:

```ts
import { models } from "@hypermode/modus-sdk-as"
import { EmbeddingsModel } from "@hypermode/modus-sdk-as/models/experimental/embeddings"

const EMBEDDING_MODEL = "minilm"

export function embedText(content: string[]): f32[][] {
  const model = models.getModel<EmbeddingsModel>(EMBEDDING_MODEL)
  const input = model.createInput(content)
  const output = model.invoke(input)
  return output.predictions
}
```

## Define Dgraph schema

We declare a schema to use Dgraph's vector search capability and create an index
on the `Product.embedding` property, even though Dgraph can function without a
schema.

To define our Dgraph schema with vector indexing support we add the
`@index(hnsw)` directive to the property storing the embedding value, in this
case `Product.embedding`. We also define the other property types and node
labels.

```rdf
<Category.name>: string @index(hash) .
<Product.category>: uid @reverse .
<Product.description>: string .
<Product.id>: string @index(hash) .
<Product.embedding>: float32vector @index(hnsw) .
```

To apply this schema to our Dgraph instance we can make a POST request to the
`/alter` endpoint of our Dgraph instance:

```bash
curl -X POST localhost:8080/alter --silent --data-binary '@dqlschema.txt'
```

or use the schema tab of the Ratel interface to apply the schema.

## Define Modus mutation function

Now we're ready to create a Modus function to create data in Dgraph. Here we
create an upsert mutation that creates a product and related category in Dgraph,
without creating duplicate nodes.

This function uses the embedding model we configured in previous steps to create
an embedding of the product description and save to the `Product.embedding`
property.

```ts
const DGRAPH_CONNECTION = "dgraph-grpc"

/**
 * Add or update a new product to the database
 */
export function upsertProduct(product: Product): Map<string, string> | null {
  let payload = buildProductMutationJson(DGRAPH_CONNECTION, product)

  const embedding = embedText([product.description])[0]
  payload = addEmbeddingToJson(payload, "Product.embedding", embedding)

  const mutation = new dgraph.Mutation(payload)
  const response = dgraph.executeMutations(DGRAPH_CONNECTION, mutation)

  return response.Uids
}
```

<Note>
  Refer to the full code
  [here](https://github.com/hypermodeinc/modus-recipes/tree/main/dgraph-101) for
  how to implement other Dgraph mutation and query functions and associated
  Dgraph helpers.
</Note>

## Dgraph `similar_to` query function

Next, we create a Modus function that uses Dgraph's `similar_to` query function
that leverages the vector index to find semantically similar products by
computing an embedding of the search term and searching for nearby product
descriptions in vector space.

```ts
/**
 * Search products by similarity to a given text
 */
export function searchProducts(search: string): Product[] {
  const embedding = embedText([search])[0]
  const topK = 3
  const body = `
    Product.id
    Product.description
    Product.title
    Product.category {
      Category.name
    }
  `
  return searchBySimilarity<Product>(
    DGRAPH_CONNECTION,
    embedding,
    "Product.embedding",
    body,
    topK,
  )
}

export function searchBySimilarity<T>(
  connection: string,
  embedding: f32[],
  predicate: string,
  body: string,
  topK: i32,
): T[] {
  const query = new dgraph.Query(`
    query search($vector: float32vector) {
        var(func: similar_to(${predicate},${topK},$vector))  {
            vemb as Product.embedding
            dist as math((vemb - $vector) dot (vemb - $vector))
            score as math(1 - (dist / 2.0))
        }

        list(func:uid(score),orderdesc:val(score))  @filter(gt(val(score),0.25)){
            ${body}
        }
    }`).withVariable("$vector", embedding)

  const response = dgraph.executeQuery(connection, query)
  console.log(response.Json)
  return JSON.parse<ListOf<T>>(response.Json).list
}
```

## Query Modus endpoint

We can run our Modus app using the `modus dev` command which generates a GraphQL
schema from the functions we've defined and start a local GraphQL endpoint for
testing and development.

Navigate to `http://localhost:8686/explorer` in your browser and use the Modus
API Explorer to first insert sample data into Dgraph using the upsert mutation
function we defined previously and then search for similar products using vector
search.

First, to create product and category nodes:

```graphql
mutation ($product: ProductInput!) {
  upsertProduct(product: $product) {
    key
    value
  }
}
```

We'll use the following values for the `product` variable creating three product
nodes ad their associated category nodes in Dgraph:

| Product ID | Title                   | Description                                                                                        | Category           |
| ---------- | ----------------------- | -------------------------------------------------------------------------------------------------- | ------------------ |
| P001       | Solar-Powered Umbrella  | A stylish umbrella with solar panels that charge your devices while you walk.                      | Outdoor Gear       |
| P002       | Self-Warming Coffee Mug | A mug that keeps your coffee at the perfect temperature using smart heating technology.            | Kitchen Appliances |
| P003       | Smart Pillow 2.0        | A pillow that tracks your sleep patterns and plays soothing sounds to help you fall asleep faster. | Smart Home         |

![Creating products in Dgraph](https://mintlify.s3.us-west-1.amazonaws.com/hypermode/images/tutorials/semantic-search/upsert.png)

And then to search for semantically similar products based on a search string we
can execute the following query, using the value of our search string for the
`$search` variable.

```graphql
query ($search: String!) {
  searchProducts(search: $search) {
    id
    title
    description
    category {
      name
    }
  }
}
```

For example, if we search using the search term "rain":

```graphql
query {
  searchProducts(search: "rain") {
    id
    title
    description
    category {
      name
    }
  }
}
```

the product search results returns our solar powered umbrella.

```json
{
  "data": {
    "searchProducts": [
      {
        "id": "P001",
        "title": "Solar-Powered Umbrella",
        "description": "A stylish umbrella with solar panels that charge your devices while you walk.",
        "category": {
          "name": "Outdoor Gear"
        }
      }
    ]
  }
}
```

Even though the description of the solar powered umbrella doesn't include the
word "rain" thanks to the meaning encoded into the embedding our semantic search
process understands the association between rain and umbrella.

## Next steps

Now that we've implemented semantic search using Dgraph, Modus, and Hypermode
hosted models using the local development experience we're ready to take the
next step and deploy our project to Hypermode. See the [Deploy Project](deploy)
section for a walk through of this process.

## Resources

* You can find the full code for this example in the
  [Modus Recipes](https://github.com/hypermodeinc/modus-recipes) GitHub
  repository:
  [https://github.com/hypermodeinc/modus-recipes/tree/main/dgraph-101](https://github.com/hypermodeinc/modus-recipes/tree/main/dgraph-101)
* Watch a video overview of this tutorial in the
  [Hypermode YouTube channel](https://www.youtube.com/@hypermodeinc):
  [https://www.youtube.com/watch?v=Z2fB-nBf4Wo](https://www.youtube.com/watch?v=Z2fB-nBf4Wo)


# User Management
Source: https://docs.hypermode.com/user-management

Add and remove users from your organization

Invite team members to your organization in Hypermode. To see who currently has
access to your organization and make changes, select the target organization
from the top navigation and then click **Users**.

## Inviting a user

You can add a new user to join your organization by sending an email invitation.
From the Users tab, click **Invite User**. In the side panel, enter the email
address of the user you wish to invite and click **Invite**.

The user is now listed as `Pending Invitation` in the `Date Joined` column of
the user list.

## Managing invitations

After sending an invitation, the user appears as `Pending Invitation` in the
organization user list.

If the user lost or didn't receive the initial invitation, click **Resend
Invite** from the `...` edit menu within the target user’s row.

If you need to cancel a sent invitation, click **Revoke Invite** from the `...`
edit menu within the target user’s row.

## Removing a user

To remove a user from your organization, identify the user you would like to
remove in the Users tab. Click the `...` to reveal the **Remove User** button.

Removing a user from your organization doesn't delete their Hypermode user
account or impact their access to other organizations.


# Work Locally
Source: https://docs.hypermode.com/work-locally

Seamless local-to-cloud experience for rapid experimentation

By using the Hyp CLI, you can access Hypermode-hosted models defined in your
[app's manifest](/modus/app-manifest). This allows for seamless and rapid
experimentation with new AI models.

## Hyp CLI setup

The Hyp CLI helps you invoke your Hypermode-hosted models from your local Modus
development environment. You can install the Hyp CLI to augment Modus and access
your Hypermode-hosted models.

```bash
npm install -g @hypermode/hyp-cli
```

## Log into Hyp

Before running `modus dev` to run your Modus app locally, ensure you're logged
into the Hyp CLI with the `hyp login` command.