Data Filtering and Sorting
When managing large amounts of data, you can create filters to search for specific information, and make queries to receive only the information you are looking for. You can use various filter attributes and sort the received data.
The Tizen API is mandatory for Tizen Mobile, Wearable, and TV profiles, which means that it is supported on all mobile, wearable, and TV devices. All mandatory APIs are supported on the Tizen emulators.
The main data handling features of the Tizen API include:
-
Filters
The Tizen API supports the following filter types, which are subtypes of the
AbstractFilter
interface (in mobile, wearable, and TV applications):-
AttributeFilter
(in mobile, wearable, and TV applications)
Matches objects containing a defined attribute or attribute value. The match is determined based on match flags defined with theFilterMatchFlag
type definition. -
AttributeRangeFilter
(in mobile, wearable, and TV applications)
Matches objects containing an attribute whose values are within a particular range. -
CompositeFilter
(in mobile, wearable, and TV applications)
Combines several filters into a set.
You can create attribute filters, attribute range filters, and composite filters to search for specific data and make complex queries. The attributes you can use with the filter types vary depending on the API you are using. For example, query methods related to the calendar, call history, contact, content, and messaging data each have their own sets of supported filter attributes.
-
-
Sorting
You can sort the results of queried data using the
SortMode
interface (in mobile, wearable, and TV applications).
Creating Attribute Filters
Learning how to create attribute filters allows you effectively incorporate query methods in your application:
-
The
AttributeFilter
filter (in mobile, wearable, and TV applications) is used to filter the search results based on an attribute value. In this example, the filter finds contacts, with the first name Chris, from the default address book.Create the filter with the
AttributeFilter
constructor. You can specify attribute options, such as the attribute name, match flag, and match value./* Use the firstName attribute with the EXACTLY match flag and the Chris value */ var firstNameFilter = new tizen.AttributeFilter('name.firstName', 'EXACTLY', 'Chris');
-
Call the
find()
method of theAddressBook
interface (in mobile and wearable applications) to find contacts. The filter (firstNameFilter
) you created is included as a parameter.tizen.contact.getDefaultAddressBook().find(successCB, errorCB, firstNameFilter);
Creating Attribute Range Filters
Learning how to use attribute range filters allows you effectively incorporate query methods in your application:
-
The
AttributeRangeFilter
filter (in mobile, wearable, and TV applications)is used to search for results based on a range of attribute values. In this example, the filter finds all events starting on a defined day from the calendar.Create the filter with the
AttributeRangeFilter
constructor. Specify the attribute, and the start and end points of the value range./* Use the startDate attribute with a range that starts today and ends in 1 day */ /* (meaning that you search for all events occurring today) */ var now = tizen.time.getCurrentDateTime(); var today_begin = new tizen.TZDate(now.getFullYear(), now.getMonth(), now.getDate()); var today_end = today_begin.addDuration(new tizen.TimeDuration(1, 'DAYS')); var dateRangeFilter = new tizen.AttributeRangeFilter('startDate', today_begin, today_end);
-
Call the
find()
method of theCalendar
interface (in mobile and wearable applications) to find events. The filter (dateRangeFilter
) you created is included as a parameter.tizen.calendar.getDefaultCalendar('EVENT').find(successCB, errorCB, dateRangeFilter);
Creating Composite Filters
Learning how to use composite filters allows you effectively incorporate query methods in your application:
-
The
CompositeFilter
filter (in mobile, wearable, and TV applications) is used to search for results based on a set of filters. In this example, the filter finds contacts, whose first name contains Chris and last name is Smith, from the default address book.Create the filter with the
CompositeFilter
constructor. You can specify multiple sub-filters for the filter set./* Create an attribute filter based on the firstName attribute */ var firstNameFilter = new tizen.AttributeFilter('name.firstName', 'CONTAINS', 'Chris'); /* Create an attribute filter based on the lastName attribute */ var lastNameFilter = new tizen.AttributeFilter('name.lastName', 'EXACTLY', 'Smith'); /* Create a composite filter based on the intersection of these 2 filters (intersection means that both filters must match for the contact to be included in the results) */ var nameCompositeFilter = new tizen.CompositeFilter('INTERSECTION', [firstNameFilter, lastNameFilter]);
-
Call the
find()
method of theAddressBook
interface (in mobile and wearable applications) to find matching contacts. The filter (nameCompositeFilter
) you created is included as a parameter.tizen.contact.getDefaultAddressBook().find(successCB, errorCB, nameCompositeFilter);
Using Sorting Modes
The following sorting modes are supported:
'ASC'
: Ascending sorting order'DESC'
: Descending sorting order
Learning how to use sorting modes allows you effectively incorporate query methods in your application:
-
The
SortMode
interface (in mobile, wearable, and TV applications) is created to sort the search results. In this example, it is used to sort contacts in the device address book in ascending order by first name.Create the sort order with the
SortMode()
method. Specify an attribute name to sort by and an order option./* Use the firstName attribute with an ASC order */ var sortMode = new tizen.SortMode('name.firstName', 'ASC');
-
Call the
find()
method of theAddressBook
interface (in mobile and wearable applications) to find matching contacts. In this example, the filter parameter in thefind()
method is defined asnull
, which means that the method retrieves all contacts in the address book.tizen.contact.getDefaultAddressBook().find(successCB, errorCB, null, sortMode);
Note
If you use a type attribute as a sort mode parameter, the sorting is not performed alphabetically since the attribute values are stored normally after the type conversion in the platform implementation.
For example, if theContentType
enumeration (in mobile, wearable, and TV applications) is the type attribute and the sorting order is"DESC"
, the sorting result is ordered according to the listed enumerator order:
- Image
- Video
- Audio
- Other
Making Complex Queries Using Filters
Learning how to use filters allows you effectively incorporate complex query methods in your application. You can create queries using AND and OR conditions, like in SQL queries. The following example shows how to make the following query:
"where ((type='VIDEO' OR type='IMAGE') AND title like '%special%')"
Basically, you search the content of the device for media items where the media type is video or image, and the title contains the word “special”.
-
Create attribute filters to include all content whose media type is either video or image:
function makeQueryAndFire() { /* Filter for the video media type */ var typeVideoFilter = new tizen.AttributeFilter('type', 'EXACTLY', 'VIDEO'); /* Filter for the image media type */ var typeImageFilter = new tizen.AttributeFilter('type', 'EXACTLY', 'IMAGE');
-
Create a composite filter that finds all content that matches one of the media type filters:
var typeFilter = new tizen.CompositeFilter('UNION', [typeVideoFilter, typeImageFilter]);
-
Create another attribute filter that includes content containing the word “special” in its title:
var titleFilter = new tizen.AttributeFilter('title', 'CONTAINS', 'special');
-
Create the final composite filter that finds all content that matches both the composite media type filter and the title filter:
var finalFilter = new tizen.CompositeFilter('INTERSECTION', [typeFilter, titleFilter]);
-
Call the
find()
method of the Content API’sContentManager
interface (in mobile, wearable, and TV applications) to retrieve the media items that match the final filter:tizen.content.find(findMediaContentsCallback, onError, null, finalFilter); }
The
findMediaContentsCallback()
event handler returns the query result.
Calendar Filter Attributes
The following table lists the filter types you can use with specific calendar item attributes in the methods of the Calendar
interface (in mobile and wearable applications).
Table: Calendar filter attributes
Attribute | Attribute filter supported | Attribute range filter supported |
---|---|---|
id |
Yes | No |
id.uid |
Yes | No |
description |
Yes | No |
summary |
Yes | No |
isAllDay |
Yes | No |
isDetached |
Yes | No |
startDate |
Yes | Yes |
location |
Yes | No |
geolocation.latitude |
Yes | Yes |
geolocation.longitude |
Yes | Yes |
organizer |
Yes | No |
visibility |
Yes | No |
status |
Yes | No |
priority |
Yes | No |
categories |
Yes | No |
dueDate |
Yes | Yes |
completedDate |
Yes | Yes |
progress |
Yes | Yes |
endDate |
Yes | Yes |
availability |
Yes | No |
lastModificationDate |
Yes | Yes |
alarms |
No* | No |
attendees |
No* | No |
recurrenceRule |
No* | No |
* The attribute filter is only supported with the EXISTS
flag.
Call History Filter Attributes
The following table lists the filter types you can use with specific call history attributes in the methods of the CallHistory interface.
Table: Call History filter attributes
Attribute | Attribute filter supported | Attribute range filter supported |
---|---|---|
uid |
Yes | Yes |
type |
Yes | No |
features |
Yes | No |
remoteParties.remoteParty |
Yes | Yes |
remoteParties.personId |
Yes | Yes |
startTime |
Yes | Yes |
duration |
Yes | Yes |
direction |
Yes | No |
Contact Filter Attributes
The following table lists the filter types you can use with specific contact attributes in the methods of the AddressBook
interface (in mobile and wearable applications).
Table: Contact filter attributes
Attribute | Attribute filter supported | Attribute range filter supported |
---|---|---|
id |
Yes | Yes |
personId |
Yes | Yes |
lastUpdated |
Yes | Yes |
isFavorite |
Yes | Yes |
birthday |
Yes | Yes |
photoURI |
Yes | No |
ringtoneURI |
Yes | No |
name.prefix |
Yes | No |
name.suffix |
Yes | No |
name.firstName |
Yes | No |
name.middleName |
Yes | No |
name.lastName |
Yes | No |
name.nicknames |
Yes | No |
name.phoneticFirstName |
Yes | No |
name.phoneticLastName |
Yes | No |
name.displayName |
Yes | No |
addresses.country |
Yes | No |
addresses.region |
Yes | No |
addresses.city |
Yes | No |
addresses.streetAddress |
Yes | No |
addresses.additionalInformation |
Yes | No |
addresses.postalCode |
Yes | No |
addresses.isDefault |
Yes | No |
addresses.types |
No | No |
phoneNumbers.number |
Yes | No |
phoneNumbers.isDefault |
Yes | No |
phoneNumbers.types |
No | No |
emails.email |
Yes | No |
emails.isDefault |
Yes | No |
emails.types |
No | No |
anniversaries.date |
Yes | Yes |
anniversaries.label |
Yes | No |
organizations.name |
Yes | No |
organizations.department |
Yes | No |
organizations.title |
Yes | No |
organizations.role |
Yes | No |
organizations.logoUri |
Yes | No |
urls.url |
Yes | No |
urls.type |
No | No |
groupIds |
Yes | Yes |
The following table lists the filter types you can use with specific person attributes in the methods of the ContactManager
interface (in mobile and wearable applications).
Table: Person filter attributes
Attribute | Attribute filter supported | Attribute range filter supported |
---|---|---|
id |
Yes | No |
displayName |
Yes | No |
contactCount |
Yes | Yes |
hasPhoneNumber |
Yes | No |
hasEmail |
Yes | No |
isFavorite |
Yes | No |
photoURI |
Yes | No |
ringtoneURI |
Yes | No |
displayContactId |
Yes | No |
Content Filter Attributes
The following table lists the filter types you can use with specific content attributes in the methods of the ContentManager
interface (in mobile, wearable, and TV applications).
Table: Content filter attributes
Attribute | Attribute filter supported | Attribute range filter supported |
---|---|---|
id |
Yes | No |
type |
Yes | No |
mimeType |
No | No |
name |
Yes | No |
title |
Yes | No |
contentURI |
Yes | No |
thumbnailURIs |
Yes | No |
releaseDate |
Yes | Yes |
modifiedDate |
Yes | Yes |
size |
No | No |
description |
No since 5.5 | No |
rating |
No since 5.5 | No since 5.5 |
geolocation.latitude |
Yes | Yes |
geolocation.longitude |
Yes | Yes |
album |
Yes | No |
genres |
Yes | No |
artists |
Yes | No |
composers |
No | No |
lyrics |
No | No |
copyright |
No | No |
bitrate |
No | No |
trackNumber |
No | No |
duration |
No | No |
orientation |
No | No |
Messaging Filter Attributes
The following tables list the filter types you can use with specific message attributes in the methods of the MessageStorage interface.
The following table lists the filter attributes related to the findMessage()
method.
Table: Filter attributes for finding messages
Attribute | Attribute filter supported | Attribute range filter supported |
---|---|---|
id |
Yes | No |
serviceId |
Yes | No |
conversationId |
No | No |
folderId |
Yes | No |
type |
Yes | No |
timestamp |
No | Yes |
from |
Yes | No |
to |
Yes | No |
cc |
Yes | No |
bcc |
Yes | No |
body.plainBody |
Yes | No |
isRead |
Yes | No |
hasAttachment |
Yes | No |
isHighPriority |
Yes | No |
subject |
Yes | No |
isResponseTo |
No | No |
messageStatus |
No | No |
attachments |
No | No |
The following table lists the filter attributes related to the findConversations()
method.
Table: Filter attributes for finding conversations
Attribute | Attribute filter supported | Attribute range filter supported |
---|---|---|
id |
Yes | No |
type |
Yes | No |
timestamp |
No | Yes |
messageCount |
Yes | No |
unreadMessages |
Yes | No |
preview |
Yes | No |
subject |
No | No |
isRead |
No | No |
from |
Yes | No |
to |
Yes | No |
cc |
No | No |
bcc |
No | No |
lastMessageId |
No | No |
The following table lists the filter attributes related to the findFolders()
method.
Table: Filter attributes for finding message folders
Attribute | Attribute filter supported | Attribute range filter supported |
---|---|---|
id |
No | No |
parentId |
No | No |
serviceId |
Yes | No |
contentType |
No | No |
name |
No | No |
path |
No | No |
type |
No | No |
synchronizable |
No | No |
Note
TheFULLSTRING
value of theFilterMatchFlag
enumerator (in mobile, wearable, and TV applications) is not supported and returns an error callback.
Related Information
- Dependencies
- Tizen 2.4 and Higher for Mobile
- Tizen 2.3.1 and Higher for Wearable
- Tizen 3.0 and Higher for TV