This is no longer maintained and has been superseded by datajoint-company/datajoint-docs. Please file new issues there (or help contribute!). We are currently migrating and generating new content until December 2022 after which we’ll be decomissioning https://docs.datajoint.org and https://tutorials.datajoint.org in favor of https://datajoint.com/docs/.
Data queries retrieve data from the database. A data query is performed with the help of a query object, which is a symbolic representation of the query that does not in itself contain any actual data. The simplest query object is an instance of a table class, representing the contents of an entire table.
For example, if
experiment.Session is a DataJoint table class, you can create a query object to retrieve its entire contents as follows:
query = experiment.Session()
More generally, a query object may be formed as a query expression constructed by applying operators to other query objects.
For example, the following query retrieves information about all experiments and scans for mouse 102 (excluding experiments with no scans):
query = experiment.Session * experiment.Scan & 'animal_id = 102'
Note that for brevity, query operators can be applied directly to class objects rather than instance objects so that
experiment.Session may be used in place of
You can preview the contents of the query in Python, Jupyter Notebook, or MATLAB by simply displaying the object.
In the image below, the object
query is first defined as a restriction of the table
EEG by values of the attribute
eeg_sample_rate greater than 1000 Hz.
Displaying the object gives a preview of the entities that will be returned by
Note that this preview only lists a few of the entities that will be returned.
Also, the preview does not contain any data for attributes of datatype
Once the desired query object is formed, the query can be executed using its fetch methods. To fetch means to transfer the data represented by the query object from the database server into the workspace of the host language.
s = query.fetch()
Here fetching from the
query object produces the NumPy record array
s of the queried data.
Checking for returned entities¶
The preview of the query object shown above displayed only a few of the entities returned by the query but also displayed the total number of entities that would be returned. It can be useful to know the number of entities returned by a query, or even whether a query will return any entities at all, without having to fetch all the data themselves.
bool function applied to a query object evaluates to
True if the query returns any entities and to
False if the query result is empty.
len function applied to a query object determines the number of entities returned by the query.
# number of sessions since the start of 2018. n = len(Session & 'session_date >= "2018-01-01"')
Normalization in queries¶
Query objects adhere to entity entity normalization just like the stored tables do. The result of a query is a well-defined entity set with an readily identifiable entity class and designated primary attributes that jointly distinguish any two entities from each other. The query operators are designed to keep the result normalized even in complex query expressions.