Pub Package Github Actions CI

Introduction

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!

Contributing

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

This is how you contribute:

  1. Fork github.com/dint-dev/dint by pressing fork button.
  2. Clone your fork to your computer: git clone github.com/your_username/database
  3. Run ./tool/pub_get.sh 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 github.com/dint-dev/dint 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:

dependencies:
  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

Libraries

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