Reading Data

There are 4 ways of reading data in your app:

  • get - Reading all documents matching a specific condition
  • getOne - Reading a single document
  • distinct - Reading the unique values of a field
  • count - Reading the count of documents matching a specific condition

Reading all documents

You can query all documents from your database that matches a particular condition by simply calling db.get on the frontend. Here's a code snippet to do so:

      
import { API, and, or, cond } from "space-api";

// Initialize api with the project name and url of the space cloud
const api = new API("todo-app", "http://localhost:8080");

// Initialize database(s) you intend to use
const db = api.Mongo();

// The condition to be matched
const condition = cond("_id", "==", 1);

// Get the todos
db.get("todos").where(condition).apply().then(res => {
    if (res.status === 200) {
      // res.data.result contains the documents returned by the database
      console.log("Response:", res.data.result);
      return;
    }
  })
  .catch(ex => {
    // Exception occured while processing request
  });
      
    
      
// Java client coming soon!    
      
    
     
# Python client coming soon!
      
    

As you would have noticed, the get method is asynchronous in nature. It takes the name of the concerned collection/table. The apply method actually triggers the given request to space-cloud and returns a promise where res.data.result is the array of documents fetched.

Reading a single document:

You can fetch a single document from your database that matches a particular condition by simply calling db.getOne on the frontend. Here's a code snippet to do so:

      
// Reading a single todo
db.getOne('todos').where(cond('_id', '==', 1)).apply().then(res => ...).catch(ex => ...);
      
    
      
// Java client coming soon!    
      
    
     
# Python client coming soon!
      
    

As you would have noticed, the getOne method is asynchronous in nature. It takes the name of the concerned collection/table. The getOne method either returns a matching document in res.data.result or returns an error (res.status - 400). The apply method actually triggers the given request to space-cloud and returns a promise where res.data.result is the required document (object).

Reading only distinct values:

You can read the distinct values of a given field by simply calling db.distinct on the frontend. Here's a code snippet to do so:

      
// Read distinct values of categories of todos
db.distinct('todos').distinctKey('category').apply().then(res => ...).catch(ex => ...);
      
    
      
// Java client coming soon!    
      
    
     
# Python client coming soon!
      
    

As you would have noticed, the distinct method is asynchronous in nature. It takes the name of the concerned collection/table. The distinctKey method takes the name of the key (field/column) for which you want to find unqiue values. The apply method actually triggers the given request to space-cloud and returns a promise where res.data.result is the array of the unique values for the given key.

Reading count of number of documents:

Sometimes, you might only want to fetch the number of documents for a given query but not the actual result or docs. In that case, you can use db.count method. Here's a code snippet to do so:

      
// Read count of todos
db.count('todos').where(cond('categories', '==', 'some-category')).apply().then(res => ...).catch(ex => ...);
      
    
      
// Java client coming soon!    
      
    
     
# Python client coming soon!
      
    

Note: count is only available in Mongo DB.

As you would have noticed, the count method is asynchronous in nature. It takes the name of the concerned collection/table. The apply method actually triggers the given request to space-cloud and returns a promise where res.data.result is an integer specifying the number of documents matching the given condition.

Read documents selectively

You can selectively read only a few documents which you desire and filter out the rest by using where clause. The where method accepts a condition object. After validation, space-cloud generates a database specific query. The documents or rows which match this query are returned.

Specifying a single condition

The cond function is used to specify a single condition as shown below:

      
// Syntax
var op1 = 'field_name';
var operator = '== | != | > | < | >= | <= | in | notIn';
var op2 = 'value';
const condition = cond(op1, operator, op2);

// Example
const condition = cond('_id', '==', '1');
db.get('todos').where(condition).apply().then(res => ...)
      
    
      
// Java client coming soon!      
      
    
      
# Python client coming soon!      
      
    

The operators allowed are:

Operator Description
== Passes if op1 is equal to op2
!= Passes if op1 is not equal to op2
> Passes if op1 is greater than op2
< Passes if op1 is lesser than op2
>= Passes if op1 is greater than or equal to op2
<= Passes if op1 is lesser than or equal to op2
in Passes if op1 is in op2
notIn Passes if op1 is not in op2

Combining multiple conditions

A single condition is often not enough to fetch the data you desire. You might need to and / or several conditions together. For e.g., you want to fetch only those posts which are of a particular author and of a particular category. The following code snippet shows how you can use and and or:

      
// AND syntax
const condition = and(...conditions)

// Example
const condition = and(cond('author', '==', 'some-author'), cond('category', '==', 'some-category'));
db.get('todos').where(condition).apply().then(res => ...);

// OR syntax
const condition = or(...conditions)

// Example
const condition = or(cond('author', '==', 'some-author'), cond('category', '==', 'some-category'));
db.get('todos').where(condition).apply().then(res => ...);
      
    
      
// Java client coming soon!      
      
    
      
# Python client coming soon!      
      
    

Dicing data as per your needs

There are variety of ways in which you can dice and slice the data you read, as per your requirements. For example you might want to read only a few selected fields of a document and not the entire document. Or you might want to limit the number of documents fetched. Here are the various ways of dicing your data:

Selecting only a few fields

You can specify which fields to be returned for the docs in the result by using select method as shown below:

      
// Return only title and author field for each post
const selectClause = { title: 1, author: 1 }
db.get('posts').where(cond('category', '==', 'some-category'))
  .select(selectClause).apply().then(res => ...);
      
    
      
// Java client coming soon!      
      
    
      
# Python client coming soon!      
      
    

Sorting

You can receive a sorted result set by using the sort function. This is how you do it:

      
// Sort syntax
db.get(collection).where(conditions).sort(...fields).apply().then()

// Example
db.get('posts').where(cond('category', '==', 'some-category'))
  .sort('title', '-author').apply().then(res => ...);
      
    
      
// Java client coming soon!      
      
    
      
# Python client coming soon!      
      
    

sort takes any number of fields as input parameters. field is a string corresponding to either field of the JSON document in case of document oriented databases like Mongo DB or name of column in case of SQL databases. The sort function sorts the result set in the order of the provided fields. For the above example, result will be sorted by title first and then by author. The minus sign in front of author means that the result set will sorted in a descending order for the author field.

Skipping

You can skip n number of rows from the beginning of the result set by using skip. It takes an integer as an parameter. This is how you can skip docs:

      
// Skip syntax
db.get(collection).where(conditions).skip(n).apply().then()

// Skip 20 rows / docs
db.get('posts').where(cond('category', '==', 'some-category'))
  .skip(20).apply().then(res => ...);
      
    
      
// Java client coming soon!      
      
    
      
# Python client coming soon!      
      
    

Limiting

You can limit the number of docs / rows returned by the server by using limit. It takes an integer as an parameter. This is how you can limit result set:

      
// Limit syntax
db.get(collection).where(conditions).limit(n).apply().then()

// Limit result up to 10 rows / docs
db.get('posts').where(cond('category', '==', 'some-category'))
  .limit(10).apply().then(res => ...);
      
    
      
// Java client coming soon!      
      
    
      
# Python client coming soon!      
      
    

Response

On response from the server, the callback passed to the then method is called with the response object as described below:

{
  "status": "number", // Status of the operation
  "data": {
    "result": "object | array | integer" // Result of the get operation
  }
}

The type of data.result depends on the operation. Its an array of objects for get, an object for getOne, an array for distinct and an integer for count operation.

Next steps

So you know how to read data from a database using Space Cloud. Now let's check how to update it.

Have a technical question?

Edit docs!