873873 - Consider adding support for summary queries to ContactsAPI

Status: RESOLVED WONTFIX

(Core Graveyard :: DOM: Contacts, enhancement)

Description

[Ben Kelly [:bkelly, not reviewing]]

Currently the ContactsAPI requires that clients retrieve all information associated with a Contact when using find() or getAll().  However, there are some very common use cases that do not require all of this data.  For example:

  1) Provide a list of contacts by name.  This only requires givenName, familyName, and ID
  2) Map a particular value, such as telephone number, to a displayable name.  This only requires givenName, familyName, tel, and ID.

On desktops its not really a problem to pull all of the information all of the time, but can be a significant source of overhead on mobile.

Consider adding support for querying a subset of Contact information.  One possible way to do this in the API is as follows.

Add findSummaries() and getAllSummaries() functions that correspond to the basic querying features of find() and getAll().  These new functions allow a summarize property to be added to the options which selects which fields to return.

Returned values are of type nsIDOMContactSummary which has read-only properties and an additional summarized property indicating the fields selected.

In addition, it should not be possible to save an nsIDOMContactSummary in order to avoid overwriting existing data with a partial entry.  Data merging is not supported.

Example code using the API.

  var options = {
    summarize: ['givenName', 'familyName']
  };
  var cursor = mozContacts.getAllSummaries(options);
  cursor.onsuccess = function(contact) {
    // use contact.givenName
    // use contact.familyName
    // use contact.id
    cursor.continue();
  };

Proof-of-concept patch to follow implementing this approach.

Comment 1

[Ben Kelly [:bkelly, not reviewing]]

Attachment: Proof-of-concept

This patch implements the API enhancement described in comment 1.

Initial testing shows some significant time improvements when loading names for 1000 contacts as defined in reference-workload-heavy.  There were 3 cases I measured:

  a) Baseline mozilla-central.
  b) Contact-summary patch requesting ['givenName', 'familyName', 'org']
  c) Contact-summary patch as in (b) + patches from bug 872741

Results in wall clock time were:

  a) ~4910ms to load all contacts / ~370ms to first contact
  b) ~4185ms to load all contacts / ~340ms to first contact
  c) ~3580ms to load all contacts / ~335ms to first contact

So this patch by itself represents a ~15% improvement.  This patch plus the IDB inList() patch combine for a ~27% improvement.  There is also a slight improvement in time to first contact callback.

Comment 2

[Reuben Morais [:reuben]]

Nice.

Comment 3

[[:fabrice] Fabrice Desré]

(In reply to Reuben Morais [:reuben] from comment #2)
> Nice.

Yep, but I think the trend is to *not* add too much cleverness in the DB of the APIs themselves because that's a never ending pursuit of new request types. We can't expose each every kind of db query to content, because that turns the contacts api in something that is more like a db api.

Comment 4

[Ben Kelly [:bkelly, not reviewing]]

(In reply to Fabrice Desré [:fabrice] from comment #3)
> Yep, but I think the trend is to *not* add too much cleverness in the DB of
> the APIs themselves because that's a never ending pursuit of new request
> types. We can't expose each every kind of db query to content, because that
> turns the contacts api in something that is more like a db api.

I'm new to the project, so I must admit I don't know the current trends.  My (perhaps naive) view, though, is that this is not a special case.

Thinking about how I use contacts on various platforms, there are very few cases where apps display the entire contact.  Really its just the main address book app doing that.

In the majority of cases apps are working with the id, name, and perhaps one other value.  Mapping a phone number to a name.  Mapping an email to a name.  Displaying a list of contact names to select from.

If we are proposing to standardize an API, it would seem useful to make these common use cases work well.

Anyway, that was my rationale for pursuing this approach.

Comment 5

[Mounir Lamouri (:mounir)]

Ben, we hope to have the Contacts API on top of a DataStore [1] and that should move the issue you are trying to fix to the application context instead of the platform one. In other words, applications would be able to arrange their data the way they want so they will be able to optimize things for their use cases.

[1] https://bugzilla.mozilla.org/show_bug.cgi?id=871445

Comment 6

[Ben Kelly [:bkelly, not reviewing]]

Unassigning for now since it doesn't look like this will move forward any time soon.

Also, I am less sure of its utility now.  For example, the tests above were based on the idea that the contacts app list only needed the name and org.  The contacts app, however, is more complex.  It also used the telephone number and email to render the list when a contact does not have a name.  These additional fields would further reduce the benefit of summarizing the contact.

Comment 7

[Ben Kelly [:bkelly, not reviewing]]

Based on the current approach to use datastore, I don't think this will ever land.  Closing as WONTFIX.