DOCSEARCHbyAlgolia
Submit Docs

TinyDB Documentation

repository·master·Indexed 27 days ago

https://github.com/msiemens/tinydb

TinyDB is a lightweight, pure-Python, document-oriented database designed for small applications. It stores data as Python dictionaries and provides a clean API for querying and managing data without external dependencies. It includes built-in JSONStorage and MemoryStorage, and supports extensibility through custom Storage classes and Middlewares. Version 4.8.2.

Tokens
10.7K
Snippets
23
Records
87
Agent score
90%

What's inside TinyDB

  1. Introduction to TinyDB

    master
    TinyDB is a lightweight, document-oriented database written in pure Python with no external dependencies. It is designed for small applications and stores data as Python dictionaries (dict). It is optimized for simplicity and ease of use, making it a suitable alternative to SQL databases or external database servers for smaller projects.

  2. Evaluate if TinyDB is suitable for your project

    master

    TinyDB is a document-oriented, pure-Python database designed for simplicity and ease of use. It stores documents as Python dict objects and requires no external server or PyPI dependencies.

    Use TinyDB if:

    • You need a simple, clean API with minimal configuration.
    • You want a lightweight, document-oriented store (similar to MongoDB).
    • You are working in a single-process environment.
    • You want to extend database behavior via custom Storages or Middlewares.
    • You are using Python 3.5+ or PyPy.

    Do NOT use TinyDB if:

    • You require ACID guarantees.
    • You need to access the database from multiple processes or threads (e.g., in a Flask application).
    • You need high performance or high-speed database operations.
    • You require advanced features like table indexing, HTTP server access, or managing relationships between tables.

    If your requirements include the features above, consider alternatives like SQLite, MongoDB, Buzhug, or CodernityDB.

  3. High-performance TinyDB extensions

    master

    Several extensions are available to improve the performance of TinyDB:

    • tinydb-rust: A drop-in reimplementation of TinyDB using Rust for improved performance. (Status: beta)
    • BetterJSONStorage: A faster 'Storage Type' that utilizes the orjson library for parsing and BLOSC for compression. (Status: stable)
    • tinydb-smartcache: Provides a smart query cache that updates during insertions, removals, or updates to prevent invalidation. Ideal for workloads with frequent queries and infrequent data changes. (Status: stable)

  6. Combine queries with logical operators

    master

    You can combine or negate queries using logical operators.

    CRITICAL: Due to Python's operator precedence, you must wrap individual conditions in parentheses when using & (AND) or | (OR), and you must wrap the query you wish to negate in parentheses when using ~ (NOT).

    Note: Comparisons only support literal values on the right-hand side. For field-to-field comparisons, use a lambda predicate.

  8. Update data in TinyDB

    master

    Update documents using either a dictionary of fields or an operation function. To update all documents in the database, omit the query argument. For complex updates (like deleting a key or incrementing a value), pass an operation function instead of a dictionary.

    # Update all documents
db.update({'foo': 'bar'})

# Update matching documents using an operation (e.g., delete a key)
from tinydb.operations import delete
db.update(delete('key1'), User.name == 'John')

# Perform multiple different updates at once
db.update_multiple([
    ({'int': 2}, where('char') == 'a'),
    ({'int': 4}, where('char') == 'b'),
])

# Mix dictionary updates with operations in update_multiple
db.update_multiple([
    ({'int': 2}, where('char') == 'a'),
    ({delete('int'), where('char') == 'b}),
])

  9. Initialize TinyDB and insert documents

    master

    To use TinyDB, import TinyDB and initialize it with a file path. You can then use the .insert() method to add documents (dictionaries) to the database.

    from tinydb import TinyDB, Query

db = TinyDB('/path/to/db.json')
db.insert({'int': 1, 'char': 'a'})
db.insert({'int': 1, 'char': 'b'})

  10. Construct queries using the Query object

    master

    You can construct queries using the Query object, which allows for attribute-style access to fields. This syntax supports nested fields and dictionary-style access for field names that are not valid Python identifiers (e.g., containing hyphens).

    To handle complex data types that JSON cannot serialize, you can implement a custom storage class using libraries like pickle or PyYAML.

    from tinydb import Query
User = Query()

# Basic field access
db.search(User.name == 'John')

# Nested field access
db.search(User.birthday.year == 1990)

# Dictionary-style access for invalid Python identifiers
db.search(User['country-code'] == 'foo')

# Using a transform function on a field
from unidecode import unidecode
db.search(User.name.map(unidecode) == 'Jose')