Glossary

storage

A place where data is stored. Provides a single namespace. Key/value stores can be represented with a single storage object, some other databases will require multiple storage objects (e.g. each “database” of CouchDB or each “collection” of MongoDB). Docu does not use nested namespaces because in document databases they mean nothing anyway.

Doqu offers a uniform API for different databases by providing “storage adapters”. See Backend API for technical details and Extensions for a list of adapters bundled with Docu.

record

A piece of data identified by an arbitrary unique primary key in a storage. In key/value stores the body of the record will be called “value” (usually serialized to a string); in other databases it is called “document” (also serialized as JSON, BSON, etc.). To avoid confusion we call all these things “records”. In Python the record is represented as a dictionary of fields.

field

A named property of a record or document. Records are actually containers for fields. There can be only one field with given name in the same record/document.

document

An dictionary with metadata. Can be associated with a record in a storage. The structure can be restricted by schema. Optional validators determine how should the document look before it can be saved into the storage, or what records can be associated with documents of given class. Special behaviour can abe added with methods of the Document subclass (see Document API).

The simplest document is just a dictionary with some metadata. The metadata can be empty or contain information about where the document comes from, what does its record look like, etc.

A document without schema or validators is equal to its record. A document with schema is only equal to the record if they have the same sets of fields and these fields are valid (i.e. have correct data types and pass certain tests).

As you see, there is a difference between documents and records but sometimes it’s very subtle.

schema

A mapping of field names to Python data types. Prescribes the structure of a document.

validator

Contains a certain test. When associated with a field of a document, determines whether given value is suitable for the field and, therefore, whether the document is valid in general. An invalid document cannot be saved to the storage. A validator can also contribute to the document query. See Validators for details on how this works.

document query

A query that yields all records within given storage that can be associated with certain document. A document without validators does not add any conditions to the query, i.e. yields all records whatever structure they have. Validators can require that some fields are present or pass certain tests.