modusdb

README

Docs · Discord

ModusDB is a high-performance, transactional database system. It's designed to be type-first, schema-agnostic, and portable. ModusDB provides object-oriented APIs that makes it simple to build new apps, paired with support for advanced use cases through the Dgraph Query Language (DQL). A dynamic schema allows for natural relations to be expressed in your data with performance that scales with your use case.

ModusDB is available as a Go package for running in-process, providing low-latency reads, writes, and vector searches. We’ve made trade-offs to prioritize speed and simplicity.

The modus framework is optimized for apps that require sub-second response times. ModusDB augments polyglot functions with simple to use data and vector storage. When paired together, you can build a complete AI semantic search or retrieval-augmented generation (RAG) feature with a single framework.

Quickstart

package main

import (
  "github.com/hypermodeinc/modusdb"
)

type User struct {
  Gid  uint64 `json:"gid,omitempty"`
  Id   string `json:"id,omitempty" db:"constraint=unique"`
  Name string `json:"name,omitempty"`
  Age  int    `json:"age,omitempty"`
}

func main() {
  db, err := New(NewDefaultConfig("/tmp/modusdb"))
  if err != nil {
    panic(err)
  }
  defer db.Close()

  gid, user, err := modusdb.Upsert(db, User{
    Id:   "123",
    Name: "A",
    Age:  10,
  })
  if err != nil {
    panic(err)
  }
  fmt.Println(user)

  _, queriedUser, err := modusdb.Get[User](db, gid)
  if err != nil {
    panic(err)
  }
  fmt.Println(queriedUser)

  _, _, err = modusdb.Delete[User](db, gid)
  if err != nil {
    panic(err)
  }
}

Open Source

The modus framework, including modusDB, is developed by Hypermode as an open-source project, integral but independent from Hypermode.

We welcome external contributions. See the CONTRIBUTING.md file if you would like to get involved.

Modus and its components are Copyright 2025 Hypermode Inc., and licensed under the terms of the Apache License, Version 2.0. See the LICENSE file for a complete copy of the license. If you have any questions about modus licensing, or need an alternate license or other arrangement, please contact us at hello@hypermode.com.

Acknowledgements

ModusDB builds heavily upon packages from the open source projects of Dgraph (graph query processing and transaction management), Badger (data storage), and Ristretto (cache). We expect the architecture and implementations of modusDB and Dgraph to expand in differentiation over time as the projects optimize for different core use cases, while maintaining Dgraph Query Language (DQL) compatibility.

Documentation

Index

• Variables
• func Create[T any](db *DB, object T, ns ...uint64) (uint64, T, error)
• func Delete[T any, R UniqueField](db *DB, uniqueField R, ns ...uint64) (uint64, T, error)
• func Get[T any, R UniqueField](db *DB, uniqueField R, ns ...uint64) (uint64, T, error)
• func Query[T any](db *DB, queryParams QueryParams, ns ...uint64) ([]uint64, []T, error)
• func Upsert[T any](db *DB, object T, ns ...uint64) (uint64, T, bool, error)
• type Config
  • func NewDefaultConfig(dir string) Config
  • func (cc Config) WithLimitNormalizeNode(n int) Config
• type ConstrainedField
• type DB
  • func New(conf Config) (*DB, error)
  • func (db *DB) AlterSchema(ctx context.Context, sch string) error
  • func (db *DB) Close()
  • func (db *DB) CreateNamespace() (*Namespace, error)
  • func (db *DB) DropAll(ctx context.Context) error
  • func (db *DB) DropData(ctx context.Context) error
  • func (db *DB) GetNamespace(nsID uint64) (*Namespace, error)
  • func (db *DB) LeaseUIDs(numUIDs uint64) (*pb.AssignedIds, error)
  • func (db *DB) Load(ctx context.Context, schemaPath, dataPath string) error
  • func (db *DB) LoadData(inCtx context.Context, dataDir string) error
  • func (db *DB) Mutate(ctx context.Context, ms []*api.Mutation) (map[string]uint64, error)
  • func (db *DB) Query(ctx context.Context, q string) (*api.Response, error)
• type Filter
• type ModusDbOption
  • func WithNamespace(namespace uint64) ModusDbOption
• type Namespace
  • func (n *Namespace) AlterSchema(ctx context.Context, sch string) error
  • func (n *Namespace) DropData(ctx context.Context) error
  • func (n *Namespace) ID() uint64
  • func (n *Namespace) Load(ctx context.Context, schemaPath, dataPath string) error
  • func (n *Namespace) LoadData(inCtx context.Context, dataDir string) error
  • func (n *Namespace) Mutate(ctx context.Context, ms []*api.Mutation) (map[string]uint64, error)
  • func (n *Namespace) Query(ctx context.Context, query string) (*api.Response, error)
• type Pagination
• type QueryParams
• type Sorting
• type StringPredicate
• type UniqueField
• type VectorPredicate

Variables

var (
	ErrSingletonOnly        = errors.New("only one modusDB instance is supported")
	ErrEmptyDataDir         = errors.New("data directory is required")
	ErrClosedDB             = errors.New("modusDB instance is closed")
	ErrNonExistentNamespace = errors.New("namespace does not exist")
)

Functions

func Create

func Create[T any](db *DB, object T, ns ...uint64) (uint64, T, error)

func Delete

func Delete[T any, R UniqueField](db *DB, uniqueField R, ns ...uint64) (uint64, T, error)

func Get

func Get[T any, R UniqueField](db *DB, uniqueField R, ns ...uint64) (uint64, T, error)

func Query

func Query[T any](db *DB, queryParams QueryParams, ns ...uint64) ([]uint64, []T, error)

func Upsert

func Upsert[T any](db *DB, object T, ns ...uint64) (uint64, T, bool, error)

Types

type Config

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

func NewDefaultConfig

func NewDefaultConfig(dir string) Config

func (Config) WithLimitNormalizeNode

func (cc Config) WithLimitNormalizeNode(n int) Config

type ConstrainedField

type ConstrainedField struct {
	Key   string
	Value any
}

type DB

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

DB is an instance of modusDB. For now, we only support one instance of modusDB per process.

func New

func New(conf Config) (*DB, error)

New returns a new modusDB instance.

func (*DB) AlterSchema

func (db *DB) AlterSchema(ctx context.Context, sch string) error

func (*DB) Close

func (db *DB) Close()

Close closes the modusDB instance.

func (*DB) CreateNamespace

func (db *DB) CreateNamespace() (*Namespace, error)

func (*DB) DropAll

func (db *DB) DropAll(ctx context.Context) error

DropAll drops all the data and schema in the modusDB instance.

func (*DB) DropData

func (db *DB) DropData(ctx context.Context) error

func (*DB) GetNamespace

func (db *DB) GetNamespace(nsID uint64) (*Namespace, error)

func (*DB) LeaseUIDs

func (db *DB) LeaseUIDs(numUIDs uint64) (*pb.AssignedIds, error)

func (*DB) Load

func (db *DB) Load(ctx context.Context, schemaPath, dataPath string) error

func (*DB) LoadData

func (db *DB) LoadData(inCtx context.Context, dataDir string) error

func (*DB) Mutate

func (db *DB) Mutate(ctx context.Context, ms []*api.Mutation) (map[string]uint64, error)

func (*DB) Query

func (db *DB) Query(ctx context.Context, q string) (*api.Response, error)

type Filter

type Filter struct {
	Field  string
	String StringPredicate
	Vector VectorPredicate
	And    *Filter
	Or     *Filter
	Not    *Filter
}

type ModusDbOption

type ModusDbOption func(*modusDbOptions)

func WithNamespace

func WithNamespace(namespace uint64) ModusDbOption

type Namespace

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

Namespace is one of the namespaces in modusDB.

func (*Namespace) AlterSchema

func (n *Namespace) AlterSchema(ctx context.Context, sch string) error

func (*Namespace) DropData

func (n *Namespace) DropData(ctx context.Context) error

DropData drops all the data in the modusDB instance.

func (*Namespace) ID

func (n *Namespace) ID() uint64

func (*Namespace) Load

func (n *Namespace) Load(ctx context.Context, schemaPath, dataPath string) error

func (*Namespace) LoadData

func (n *Namespace) LoadData(inCtx context.Context, dataDir string) error

TODO: Add support for CSV file

func (*Namespace) Mutate

func (n *Namespace) Mutate(ctx context.Context, ms []*api.Mutation) (map[string]uint64, error)

func (*Namespace) Query

func (n *Namespace) Query(ctx context.Context, query string) (*api.Response, error)

Query performs query or mutation or upsert on the given modusDB instance.

type Pagination

type Pagination struct {
	Limit  int64
	Offset int64
	After  string
}

type QueryParams

type QueryParams struct {
	Filter     *Filter
	Pagination *Pagination
	Sorting    *Sorting
}

type Sorting

type Sorting struct {
	OrderAscField  string
	OrderDescField string
	OrderDescFirst bool
}

type StringPredicate

type StringPredicate struct {
	Equals         string
	LessThan       string
	LessOrEqual    string
	GreaterThan    string
	GreaterOrEqual string
	AllOfTerms     []string
	AnyOfTerms     []string
	AllOfText      []string
	AnyOfText      []string
	RegExp         string
}

type UniqueField

type UniqueField interface {
	uint64 | ConstrainedField
}

type VectorPredicate

type VectorPredicate struct {
	SimilarTo []float32
	TopK      int64
}