For up-to-date product documentation, see the IBM MobileFirst Foundation Developer Center.

General JSONStore terminology

Learn about general JSONStore terminology.

JSONStore document

A document is the basic building block of JSONStore.

A JSONStore document is a JSON object with an automatically generated identifier (_id) and JSON data. It is similar to a record or a row in database terminology. The value of _id is always a unique integer inside a specific collection. Some functions like the add, replace, and remove methods in the JSONStoreInstance class take an Array of Documents/Objects. These methods are useful to perform operations on various Documents/Objects at a time.


Single document

var doc = { _id: 1, json: {name: 'carlos', age: 99} };


Array of documents

var docs = [ { _id: 1, json: {name: 'carlos', age: 99} }, { _id: 2, json: {name: 'tim', age: 100} } ]

JSONStore collection

A JSONStore collection is similar to a table, in database terminology


Customer collection

[ { _id: 1, json: {name: 'carlos', age: 99} }, { _id: 2, json: {name: 'tim', age: 100} } ]

This code is not the way that the documents are stored on disk, but it is a good way to visualize what a collection looks like at a high level.

JSONStore store

A store is the persistent JSONStore file that contains one or more collections.

A store is similar to a relational database, in database terminology. A store is also referred to as a JSONStore.

JSONStore search fields

A search field is a key/value pair.

Search fields are keys that are indexed for fast lookup times, similar to column fields or attributes, in database terminology.

Extra search fields are keys that are indexed but that are not part of the JSON data that is stored. These fields define the key whose values (in the JSON collection) are indexed and can be used to search more quickly.

Valid data types are: string, boolean, number, and integer. These types are only type hints, there is no type validation. Furthermore, these types determine how indexable fields are stored. For example, {age: 'number'} will index 1 as 1.0 and {age: 'integer'} will index 1 as 1.


Search fields and extra search fields.

var searchField = {name: 'string', age: 'integer'}; var additionalSearchField = {key: 'string'};

It is only possible to index keys inside an object, not the object itself. Arrays are handled in a pass-through fashion, meaning that we cannot index an array or a specific index of the array (arr[n]), but we can index objects inside an array.

Indexing values inside an array.

var searchFields = { '' : 'string', // matches carlos and tim on myObject 'people.age' : 'integer' // matches 99 and 100 on myObject }; var myObject = { people : [ {name: 'carlos', age: 99}, {name: 'tim', age: 100} ] };

JSONStore queries

Queries are objects that use search fields or extra search fields to look for documents.

The example presumes that the name search field is of type string and the age search field is of type integer.


Find documents with name that matches carlos:

var query1 = {name: 'carlos'};

Find documents with name that matches carlos and age matches 99:

var query2 = {name: 'carlos', age: 99};

JSONStore query parts

Query parts are used to build more advanced searches. Some JSONStore operations, such as some versions of find or count take query parts. Everything within a query part is joined by AND statements, while query parts themselves are joined by OR statements. The search criteria returns a match only if everything within a query part is true. We can use more than one query part to search for matches that satisfy one or more of the query parts.

Find with query parts operate only on top-level search fields. For example: name, and not name.first. Use multiple collections where all search fields are top-level to get around this. The query parts operations that work with non top-level search fields are: equal, notEqual, like, notLike, rightLike, notRightLike, leftLike, and notLeftLike. The behavior is undetermined if we use non-top-level search fields.

Parent topic: JSONStore