Querying

IQueryable Support

IContactStore.Query() returns an IQueryable<Contact> that translates LINQ predicates to native queries where possible, with automatic in-memory fallback for unsupported filters.

On Android, predicates are translated to ContentProvider selection queries. On iOS, predicates are translated to CNContact fetch predicates.

Basic Queries

Filter by Name

var results = contactStore.Query()
    .Where(c => c.GivenName.Contains("John"))
    .ToList();

Filter by Phone Number

var results = contactStore.Query()
    .Where(c => c.Phones.Any(p => p.Number.Contains("555")))
    .ToList();

Filter by Email

var results = contactStore.Query()
    .Where(c => c.Emails.Any(e => e.Address.Contains("@example.com")))
    .ToList();

Combine Filters

var results = contactStore.Query()
    .Where(c => c.GivenName.StartsWith("J") && c.FamilyName.Contains("Smith"))
    .ToList();

Paging

var page = contactStore.Query()
    .Where(c => c.FamilyName.StartsWith("A"))
    .Skip(10)
    .Take(20)
    .ToList();

Supported Operations

Operation	Example
Contains	c.GivenName.Contains("John")
StartsWith	c.GivenName.StartsWith("J")
EndsWith	c.GivenName.EndsWith("son")
Equals	c.GivenName.Equals("John")

Filterable Properties

Direct Properties

These string properties support all four operations above:

• GivenName
• FamilyName
• MiddleName
• NamePrefix
• NameSuffix
• Nickname
• DisplayName
• Note

Collection Properties

These collections support filtering with .Any():

Collection	Filterable Field
Phones	Number
Emails	Address

Extension Methods

Get Family Name First Letters

Returns a sorted, distinct list of uppercase first letters from all contacts’ family names:

var letters = await contactStore.GetFamilyNameFirstLetters();
// ['A', 'B', 'C', 'D', ...]

This is useful for building alphabetical index/jump lists in contact list UIs.

How Native Translation Works

When you write a LINQ query, the library’s expression visitor extracts the predicate and translates it:

1. Supported filters are converted to native queries (SQL-like selection on Android, NSPredicate on iOS)
2. Unsupported filters cause a fallback to loading all contacts and filtering in memory
3. Multiple supported filters are intersected — each filter narrows the result set

Tip

For best performance, prefer the filterable properties listed above. Filtering on other properties like Addresses or Organization will load all contacts and filter in memory.