warehouses.models

Graph of models in the warehouses app and related apps.

This module defines models and model managers for storing and retrieving data.

These models provide a layer of abstraction between Cyphon and the storage engines with which it interacts.

Class	Description
Collection	A document collection, doctype, or database table.
CollectionManager	Model manager for Collections.
Warehouse	A database or search index.
WarehouseManager	Model manager for Warehouses.

class warehouses.models.Collection(*args, **kwargs)

Bases: django.db.models.base.Model

Define a document collection, document type, or database table.

warehouse

Warehouse – The Warehouse in which the Collection resides.

name

str – The name of a document collection, doc type, or database table, depending on the Warehouse backend.

exception DoesNotExist

Bases: django.core.exceptions.ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: django.core.exceptions.MultipleObjectsReturned

company

The Company associated with the Collection.

Returns:The Company associated with the Collection’s Distillery. Return type:Company

distillery

Accessor to the related object on the reverse side of a one-to-one relation.

In the example:

class Restaurant(Model):
    place = OneToOneField(Place, related_name='restaurant')

place.restaurant is a ReverseOneToOneDescriptor instance.

engine

An Engine for handling documents.

Returns:An instance of an Engine subclass that can be used to handle documents associated with the Collection. Return type:Engine

filter_ids(doc_ids, fields, value)

Find the ids of documents that match a value.

Parameters:

• doc_ids (list of str) – The ids of documents to filter.
• fields (list of DataField) – DataFields that should be examined for a matching value.
• value (str) – A value used to find matching documents.

Returns:

The subset of ids for documents containing the given value in one or more of the specified fields.

Return type:

list of str

find(query, sorter=None, page=1, page_size=10)

Find documents matching a query.

Parameters:

• query (EngineQuery) – An EngineQuery defining critieria for matching documents in the index or time series.
• sorter (Sorter or None) – A Sorter defining how results should be ordered.
• page (int) – The page of results to return.
• page_size (int) – The number of documents per page of results.

Returns:

A dictionary with keys ‘count’ and ‘results’. The ‘count’ value is the total number of documents matching the search criteria. The ‘results’ value is a list of documents from the search result, with the doc ids added to each document.

Return type:

dict

find_by_id(doc_ids)

Find one or more documents by id.

Parameters:doc_ids (str or list of str) – A document id or a list of document ids. Returns:Documents that match the given id(s). Returns a list of documents if doc_ids is a list; otherwise returns a single document. If no matches are found, returns None. Return type:dict, list of dict, or None

get_backend()

Get the backend used by the Collection.

Returns the name of the backend associated with the Collection’s Warehouse. This method can be used to display the backend in the admin list view.

Returns:The backend used by the Collection’s Warehouse. Return type:str

get_company()

Get the Company associated with the Collection.

This method is used to display the Company in the admin list view.

Returns:The Company associated with the Collection’s Distillery. Return type:Company

get_sample(doc)

Get a teaser for a doc.

Parameters:doc (dict) – A document that conforms to the Collection’s schema, which is defined by the Container used by the Collection’s Distillery. Returns:A teaser for the original the doc. Return type:dict

get_schema()

Get the DataFields used by documents in the Collection.

Returns:The DataFields in the Container used by the Collection’s Distillery. Return type:list of DataFields

get_warehouse_name()

Get the name of the Collection’s Warehouse.

This method is used to display the Warehouse name in the admin list view.

Returns:The name of the Collection’s Warehouse. Return type:str

id

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

in_time_series()

Whether the Collection’s Warehouse is a time series.

Returns a bool indicating whether the Collection’s Warehouse stores data in a time series (e.g., timestamped indexes).

Returns:Whether data is stored as a time series. Return type:bool

insert(doc)

Save a document to the Collection.

Parameters:doc (dict) – A document to insert into the data store represented by the Collection. Returns:The id of the inserted document. Return type:str

name

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

objects = <warehouses.models.CollectionManager object>

remove_by_id(doc_ids)

Remove the documents with the given ids.

Parameters:doc_ids (str or list of str) – An id or list of ids of documents to remove from the Collection. Returns: Return type:None

warehouse

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

child.parent is a ForwardManyToOneDescriptor instance.

warehouse_id

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

class warehouses.models.CollectionManager

Bases: django.db.models.manager.Manager

Manage Collection objects.

Customizes the default Django model manager by adding and overriding methods.

get_by_natural_key(backend, database, name)

Get a Collection by its natural key.

Allows retrieval of a Collection by its natural key instead of its primary key.

Parameters:

• backend (str) – The backend of the Warehouse to which the Collection belongs.
• database (str) – The name of the Warehouse to which the Collection belongs.
• name (str) – The name of the Collection.

Returns:

The Collection associated with the natural key.

Return type:

Collection

get_queryset()

Get the initial Collection queryset.

Overrides the default get_queryset method to also select related Warehouses.

Returns:A QuerySet of Collections. Return type:QuerySet

See also

Django’s documentation contains instructions on how to select related objects and modify an initial queryset.

class warehouses.models.Warehouse(*args, **kwargs)

Bases: django.db.models.base.Model

Define a database or search index.

backend

str – Lowercase name of a storage engine, such as ‘elasticsearch’. This corresponds to the base file name of the module containing the Engine subclass for that storage engine. Choices are constrained to BACKEND_CHOICES.

name

str – The name of a database or search index.

time_series

bool – Whether data should be stored as a time series (e.g., timestamped indexes).

exception DoesNotExist

Bases: django.core.exceptions.ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: django.core.exceptions.MultipleObjectsReturned

backend

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

clean()

Validate the model as a whole.

Provides custom model validation. If time_series is True, checks that the backend can work with a time series.

Returns: Return type:None Raises:ValidationError – If time_series is True but the selected backend cannot work with a time series, or if any default Django model validations fail.

See also

See Django’s documentation for the clean() method.

collections

Accessor to the related objects manager on the reverse side of a many-to-one relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

parent.children is a ReverseManyToOneDescriptor instance.

Most of the implementation is delegated to a dynamically defined manager class built by create_forward_many_to_many_manager() defined below.

get_backend_display(**morekwargs)

get_module()

Get the module for interacting with the backend.

Returns:The module that contains the Engine subclass for interacting with the Warehouse’s backend. Return type:module

id

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

name

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

objects = <warehouses.models.WarehouseManager object>

time_series

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

class warehouses.models.WarehouseManager

Bases: django.db.models.manager.Manager

Manage Warehouse objects.

Adds methods to the default Django model manager.

get_by_natural_key(backend, name)

Get a Warehouse by its natural key.

Allows retrieval of a Warehouse by its natural key instead of its primary key.

Parameters:

• backend (str) – The backend of the Warehouse.
• name (str) – The name of the Warehouse.

Returns:

The Warehouse associated with the natural key.

Return type:

Warehouse