Tutorials

Advanced Filtering and Searching

This section will describe advanced usage of the Android and Java API, in order to filter, sort and order responses. The upcoming samples are using the following setup: space id = cfexampleapi and api token = b4c0n73n7fu1.

Searching

In order query for all items, containing the complete string nyan in symbol or text fields.

1CDAArray found = client.fetch(CDAEntry.class)
2    .where("query", "nyan")
3    .all();

Inexact searches

If you want to search for just a part of a text, you could use a match operator. Keep in mind, you have to define the field to be matched, so it won’t work on all fields automatically. Also for this request to work, you have to specify a content type to look for:

1CDAArray found = client.fetch(CDAEntry.class)
2    .where("content_type", "cat")
3    .where("fields.name[match]", "yan")
4    .all();

Order

In order to order a result by a field, you need to specify order as a where selector. Please make sure, that you either just query for fields in sys, or specify a content type to look for.

1CDAArray found = client.fetch(CDAEntry.class)
2    .where("order", "sys.id")
3    .all();

If you want to invert the result order, feel free to add a - in front of the field to be looked for:

1CDAArray found = client.fetch(CDAEntry.class)
2    .where("order", "-sys.id")
3    .all();

Having a result ordered in more then one level, take a look at this snippet:

1CDAArray found = client.fetch(CDAEntry.class)
2    .where("order", "sys.contentType.sys.id,sys.id")
3    .all();

Limit

To retrieve a given amount of elements, you can use the limit parameter.

1CDAArray found = client.fetch(CDAEntry.class)
2    .where("limit", "1")
3    .all();

Ignoring the first entries, can be accomplished by using the skip parameter. This can be used nicely for paging, by skipping the first 13 elements:

1CDAArray found = client.fetch(CDAEntry.class)
2    .where("skip", "13")
3    .all();

Include

If you do not want the query to return only top level entries, and not its children, you could use the parameter include with the value 0. Otherwise this value will be used to determine how many hierarchy levels to be returned. If not set, it will return 1, only the first level of children.

1CDAArray found = client.fetch(CDAEntry.class)
2    .where("include", "0")
3    .all();

Sequences

Do you want to get elements based on a set of possibilities? Then you came to the right place:

1CDAArray found = client.fetch(CDAEntry.class)
2    .where("sys.id[in]", "finn,jake")
3    .all();

Will return all elements whose sys.id is either finn or jake.

If you want to invert this query, you would use the a nin (for notin) operator in the query:

1CDAArray found = client.fetch(CDAEntry.class)
2    .where("content_type", "cat")
3    .where("sys.id[nin]", "nyancat")
4    .all();

Existence

Querying for all entries having a specific field set to something (aka it is existing), you would issue a request like:

1CDAArray found = client.fetch(CDAEntry.class)
2    .where("sys.id[exists]", "false") // entries without id
3    .all();

Mathematical comparisons

Contentful is also able to query entries, based on a mathematical comparison operator:

1CDAArray found = client.fetch(CDAEntry.class)
2    .where("content_type", "cat")
3    .where("fields.birthday[lte]", "1980-01-01")
4    .all();

This will return all entries with the birthday less or equal then 1980-01-01. Other operators are available too, see REST API doc

Inequality

If you want to filter out specific items, you should be thinking about using the [ne] operator:

1CDAArray found = client.fetch(CDAEntry.class)
2    .where("sys.id[ne]", "nyancat")
3    .all();

Location

Did you ever want to query based on a real world location? This is how to do this in java:

1CDAArray found = client.fetch(CDAEntry.class)
2    .where("content_type", "1t9IbcfdCk6m04uISSsaIK")
3    .where("fields.center[near]", "38,-122")
4    .all();

Which will return the list of results ordered by distance, the closest first.

If you would rather find out if there are entries in a specific area of the world, you could be using something like this:

1CDAArray found = client.fetch(CDAEntry.class)
2    .where("content_type", "1t9IbcfdCk6m04uISSsaIK")
3    .where("fields.center[within]", "40,-124,36,-120")
4    .all();

returning all elements whose center is in the given area. (Do not forget the content_type)

Assets mimetype

This last example will tell you how to query for assets, which are only of a specific mimetype:

1CDAArray found = client.fetch(CDAAsset.class)
2    .where("mimetype_group", "image")
3    .all();

Next steps