Search with the Where Clause¶

A where clause is a condition which references columns of a data table where the query is sent. For any given query Backendless returns the data records which match the condition in the where clause. A where clause is a query string which must conform to a subset of the SQL-92 standard. The subset of the syntax supported by Backendless is the part that goes into the WHERE clause of an SQL query. This is the reason why we refer to it as the where clause. For example, consider the following data objects, specifically notice the columns name and age:

Values for columns of types STRING and TEXT must be wrapped in single quotes. Suppose you need to retrieve an object where the value of the name property is "Joe". This can be accomplished with the following where clause:

name = 'Joe'

If the value itself has a single quote, it can be "escaped" by adding an additional single quote. For example:

name = 'Charlie''s Angels'

If you need all objects where the age column contains a value less than 30:

age < 30

Just like in SQL, columns can be combined in a single where clause. The following condition would retrieve all objects containing letter J in the name and the age column's value is greater than 20:

name LIKE 'J%' and age > 20

Condition	Sample where clause	Column type
Value in a column equals a string literal.	`name = 'foo'`	STRING, TEXT or EXTENDED STRING
Value in a column does not equal a string literal.	`name != 'foo'`	STRING, TEXT or EXTENDED STRING
Value in a column is not assigned	`name is null`	STRING, TEXT or EXTENDED STRING
Value in a column is assigned	`name is not null`	STRING, TEXT or EXTENDED STRING
Value in a column contains a substring literal	`name LIKE '%foo%'`	STRING, TEXT or EXTENDED STRING
Value in a column ends with a substring literal	`name LIKE '%foo'`	STRING, TEXT or EXTENDED STRING
Value in a column starts with a substring literal	`name LIKE 'foo%'`	STRING, TEXT or EXTENDED STRING
Value in a column is one of enumerated string literals.	`name IN ('value1', 'value2', 'value3)` or `name = 'value1' OR name = 'value2' or name = 'value3'`	STRING, TEXT or EXTENDED STRING
Value in a column equals a numeric literal	`age = 21`	INT or DOUBLE
Value in a column is greater than a numeric literal	`age > 21`	INT or DOUBLE
Value in a column is greater than or equal a numeric literal	`age >= 21`	INT or DOUBLE
Value in a column is less than a numeric literal	`age < 21`	INT or DOUBLE
Value in a column is less than or equal a numeric literal	`age <= 21`	INT or DOUBLE

Examples

Using Dictionary

You do not need to declare/write any custom classes when using the Dictionary approach. Data objects are represented as System.Collections.Generic.Dictionary objects. Column names become map property names and the object values are corresponding property values. === "Custom Class"

Consider the following class:

namespace com.sample 
{
  public class Contact
  {
    [SetClientClassMemberName( "objectId" )]
    public String ObjectId {get; set;};
    public String Name {get; set;};
    public int Age {get; set;};
    public String Phone {get; set;};
    public String Title {get; set;};
  }
}

Find all contacts where the value of the "age" property equals 47:

Using DictionaryCustom Class

String whereClause = "age = 47";
DataQueryBuilder queryBuilder = DataQueryBuilder.Create();
queryBuilder.SetWhereClause( whereClause );

// ***********************************************************
// Blocking API:
// ***********************************************************
IList<Dictionary<string, object>> result = Backendless.Data.Of( "Contact" ).Find( queryBuilder );

// ***********************************************************
// Non-blocking API:
// ***********************************************************
AsyncCallback<IList<Dictionary<string, object>>> findCallback;
findCallback = new AsyncCallback<IList<Dictionary<string, object>>>(
  foundObjects =>
  {
    System.Console.WriteLine( "Server returned " + foundObjects.Count + " objects" );
  },
  error =>
  {
    System.Console.WriteLine( "Server returned an error " + error.Message );
  } );

Backendless.Data.Of( "Contact" ).Find( queryBuilder, findCallback );

String whereClause = "age = 47";
DataQueryBuilder queryBuilder = new DataQueryBuilder.Create();
queryBuilder.SetWhereClause( whereClause );

// ***********************************************************
// Blocking API:
// ***********************************************************
IList<Contact> result = Backendless.Data.Of<Contact>().Find( queryBuilder );

// ***********************************************************
// Non-blocking API:
// ***********************************************************
AsyncCallback<IList<Contact>> findCallback;
findCallback = new AsyncCallback<IList<Contact>>(
  foundObjects =>
  {
    System.Console.WriteLine( "Server returned " + foundObjects.Count + " objects" );
  },
  error =>
  {
    System.Console.WriteLine( "Server returned an error " + error.Message );
  } );

Backendless.Data.Of<Contact>().Find( queryBuilder, findCallback );

Find all contacts where the value of the "age" property is greater than 21:

Using DictionaryCustom Class

String whereClause = "age > 21";
DataQueryBuilder queryBuilder = DataQueryBuilder.Create();
queryBuilder.SetWhereClause( whereClause );

// ***********************************************************
// Blocking API:
// ***********************************************************
IList<Dictionary<string, object>> result = Backendless.Data.Of( "Contact" ).Find( queryBuilder );

// ***********************************************************
// Non-blocking API:
// ***********************************************************
AsyncCallback<IList<Dictionary<string, object>>> findCallback;
findCallback = new AsyncCallback<IList<Dictionary<string, object>>>(
  foundObjects =>
  {
    System.Console.WriteLine( "Server returned " + foundObjects.Count + " objects" );
  },
  error =>
  {
    System.Console.WriteLine( "Server returned an error " + error.Message );
  } );

Backendless.Data.Of( "Contact" ).Find( queryBuilder, findCallback );

String whereClause = "age > 21";
DataQueryBuilder queryBuilder = new DataQueryBuilder.Create();
queryBuilder.SetWhereClause( whereClause );

// ***********************************************************
// Blocking API:
// ***********************************************************
IList<Contact> result = Backendless.Data.Of<Contact>().Find( queryBuilder );

// ***********************************************************
// Non-blocking API:
// ***********************************************************
AsyncCallback<IList<Contact>> findCallback;
findCallback = new AsyncCallback<IList<Contact>>(
  foundObjects =>
  {
    System.Console.WriteLine( "Server returned " + foundObjects.Count + " objects" );
  },
  error =>
  {
    System.Console.WriteLine( "Server returned an error " + error.Message );
  } );

Backendless.Data.Of<Contact>().Find( queryBuilder, findCallback );

Find all contacts by name:

Using DictionaryCustom Class

String whereClause = "name = 'Jack Daniels'";
DataQueryBuilder queryBuilder = DataQueryBuilder.Create();
queryBuilder.SetWhereClause( whereClause );

// ***********************************************************
// Blocking API:
// ***********************************************************
IList<Dictionary<string, object>> result = Backendless.Data.Of( "Contact" ).Find( queryBuilder );

// ***********************************************************
// Non-blocking API:
// ***********************************************************
AsyncCallback<IList<Dictionary<string, object>>> findCallback;
findCallback = new AsyncCallback<IList<Dictionary<string, object>>>(
  foundObjects =>
  {
    System.Console.WriteLine( "Server returned " + foundObjects.Count + " objects" );
  },
  error =>
  {
    System.Console.WriteLine( "Server returned an error " + error.Message );
  } );

Backendless.Data.Of( "Contact" ).Find( queryBuilder, findCallback );

String whereClause = "name = 'Jack Daniels'";
DataQueryBuilder queryBuilder = new DataQueryBuilder.Create();
queryBuilder.SetWhereClause( whereClause );

// ***********************************************************
// Blocking API:
// ***********************************************************
IList<Contact> result = Backendless.Data.Of<Contact>().Find( queryBuilder );

// ***********************************************************
// Non-blocking API:
// ***********************************************************
AsyncCallback<IList<Contact>> findCallback;
findCallback = new AsyncCallback<IList<Contact>>(
  foundObjects =>
  {
    System.Console.WriteLine( "Server returned " + foundObjects.Count + " objects" );
  },
  error =>
  {
    System.Console.WriteLine( "Server returned an error " + error.Message );
  } );

Backendless.Data.Of<Contact>().Find( queryBuilder, findCallback );

Find all contacts by partial name match:

Using Java MapCustom Class

String whereClause = "name LIKE 'Jack%'";
DataQueryBuilder queryBuilder = DataQueryBuilder.Create();
queryBuilder.SetWhereClause( whereClause );

// ***********************************************************
// Blocking API:
// ***********************************************************
IList<Dictionary<string, object>> result = Backendless.Data.Of( "Contact" ).Find( queryBuilder );

// ***********************************************************
// Non-blocking API:
// ***********************************************************
AsyncCallback<IList<Dictionary<string, object>>> findCallback;
findCallback = new AsyncCallback<IList<Dictionary<string, object>>>(
  foundObjects =>
  {
    System.Console.WriteLine( "Server returned " + foundObjects.Count + " objects" );
  },
  error =>
  {
    System.Console.WriteLine( "Server returned an error " + error.Message );
  } );

Backendless.Data.Of( "Contact" ).Find( queryBuilder, findCallback );

String whereClause = "name LIKE 'Jack%'";
DataQueryBuilder queryBuilder = new DataQueryBuilder.Create();
queryBuilder.SetWhereClause( whereClause );

// ***********************************************************
// Blocking API:
// ***********************************************************
IList<Contact> result = Backendless.Data.Of<Contact>().Find( queryBuilder );

// ***********************************************************
// Non-blocking API:
// ***********************************************************
AsyncCallback<IList<Contact>> findCallback;
findCallback = new AsyncCallback<IList<Contact>>(
  foundObjects =>
  {
    System.Console.WriteLine( "Server returned " + foundObjects.Count + " objects" );
  },
  error =>
  {
    System.Console.WriteLine( "Server returned an error " + error.Message );
  } );

Backendless.Data.Of<Contact>().Find( queryBuilder, findCallback );

Codeless Reference¶

Consider the following data table:

For demonstration purposes, this Codeless Reference section has only one example which describes all use-cases of the where clause presented in the Examples section of this topic: Refer to the Examples section to find description for every Codeless use-case presented below:

The numbering in the list presented below is also referenced in the screenshot of the Codeless logic example:

1. Find all contacts where the value of the "age" property equals 20.

2. Find all contacts where the value of the "age" property is greater than 21.

3. Find all contacts where the value of the "age" property is between 21 and 40.

4. Find all contacts whose "age" property is 30 or 10.

5. Find all contacts by name 'Joe'.

6. Find all contacts whose name is 'Joe' or 'Kevin':

7. Find all contacts by partial name match.

data_service_search_with_the_where_clause

Important

For a detailed description of all input parameters see the Basic Object Retrieval topic of this guide.