Pub Package Github Actions CI


Warning: this package isn't ready for use!

The package aims to be usable with:

  • SQL databases
  • Document databases (like Google Cloud Firestore)
  • Search engines (like ElasticSearch/Lucene)

The current iteration of the API has a single API for all three database paradigms. This is somewhat unconventional and carries a risk of confusion when developers read documentation or make assumptions about behavior. We evaluate the current approach, and if it doesn't seem right, split the unified API into two or three libraries.

Any feedback on the design is appreciated. The project is licensed under the Apache License 2.0. If this project interests you, please consider becoming a developer/maintainer.

Available adapters

In this package

In other packages

The following packages are currently far from passing tests:

Available middleware classes

In this package

Other packages

  • search (Github)
    • An minimalistic search engine for small collections.
  • Have a package? Add it here!


This is an open-source community project. Anyone, even beginners, can contribute.

This is how you contribute:

  1. Fork by pressing fork button.
  2. Clone your fork to your computer: git clone
  3. Run ./tool/ to get dependencies for all packages.
  4. Do your changes.
  5. When you are done, commit changes with git add -A and git commit.
  6. Push changes to your personal repository: git push origin
  7. Go to and create a pull request.

Contributors may be added to the Github organization team so they can save time by pushing directly to the repository.

Getting started

Add dependency

In pubspec.yaml, add:

  database: any

Construct instance

import 'package:database/database.dart';

Future<void> main() async {
  // Use in-memory database
  final database = MemoryDatabase();

  // ...

Write and read documents

// Insert
final document = await database.collection('employee').insert({
  'name': 'Jane',
  'title': 'software developer',
  'skills': ['dart'],

// Update
await document.update({
  // ...

// Read
await snapshot = document.get();

// DElete
await document.delete();

Query documents

final result = await database.collection('employee').search(
  query: Query.parse('name:(John OR Jane)')

for (var snapshot in result.snapshots) {
  // ...

Introduction to filters

  • Logical
    • AndFilter([ValueFilter('f0'), ValueFilter('f1')])
    • OrFilter([ValueFilter('f0'), ValueFilter('f1')])
    • NotFilter(ValueFilter('example'))
  • Structural
    • ListFilter(items: ValueFilter('value'))
    • MapFilter({'key': ValueFilter('value')})
  • Primitive
    • ValueFilter(3.14)
    • RangeFilter(min:3, max:4)
    • RangeFilter(min:3, max:4, isExclusiveMin:true, isExclusiveMax:true)
    • RangeFilter(min:3, max:4, isExclusiveMin:true, isExclusiveMax:true)
    • GeoPointFilter(near:GeoPoint(1.23, 3.45)
  • SQL filters
    • SqlFilter('SELECT * FROM table WHERE x ', 3.14)
  • Natural language filters
    • KeywordFilter('example')
      • Keyword queries (KeyFilter) are very expensive unless you have configured a search engine such as ElasticSearch/Lucene. The default implementation visits every document in the collection and does a substring search.
      • To prevent unintentional visit to every document, remote databases should throw UnsuportedError unless they support keyword search.

Parsing filters

The package supports parsing query strings. The syntax is inspired by Lucene and Google Search.

final query = Query.parse('New York Times date:>=2020-01-01');

Examples of supported queries:

  • New York Times
    • Matches keywords "New", "York", and "Times". The underlying search engine may decide to focus on the three words separately, sequence "New York", or sequence "New York Times".
  • "New York Times"
    • A quoted keyword ensures that the words must appear as a sequence.
  • cat AND dog
    • Matches keywords "cat" and "dog" (in any order).
  • cat OR dog
    • Matches keyword "cat", "dog", or both.
  • pet -cat
    • Matches keyword "pet", but excludes documents that match keyword "cat".
  • color:brown
    • Color matches keyword "brown".
  • color:="brown"
    • Color is equal to "brown".
  • weight:>=10
    • Weight is greater than or equal to 10.
  • weight:[10 TO 20]
    • Weight is between 10 and 20, inclusive.
  • weight:{10 TO 20}
    • Weight is between 10 and 20, exclusive.
  • (cat OR dog) AND weight:>=10
    • An example of grouping filters.

Supported primitives


An unified database API. [...]
Classes used by database adapters. [...]
Contains various database adapters that use browser APIs. [...]
Converts Dart objects to simpler Dart (Map) values and vice-versa. [...]
Supports for a Lucene-like search query syntax. [...]