Querying

The Query class provides a powerful, fluent API for building and executing database queries. Inspired by Apple's Cocoa Predicates and LINQ, it offers a clean, readable syntax for expressing complex query logic.

Query Construction

Basic Factory Methods

1// Query a specific type
2Query<Article> query = Query.from(Article.class);
3
4// Query all types
5Query<Object> allQuery = Query.fromAll();
6
7// Query by ObjectType
8ObjectType articleType = ObjectType.getInstance(Article.class);
9Query<Article> typeQuery = Query.fromType(articleType);
10
11// Query by type group (multiple related types)
12Query<Content> contentQuery = Query.fromGroup("content");

Using a Specific Database

1Database searchDb = Database.Static.getInstance("search");
2
3Query<Article> query = Query.from(Article.class)
4    .using(searchDb);

Predicates and Filtering

where - Initial Predicate

Set the initial query predicate:

1// Simple equality
2Query.from(Article.class)
3    .where("title = ?", "Getting Started");
4
5// Comparison
6Query.from(Article.class)
7    .where("publishDate > ?", cutoffDate);
8
9// Multiple parameters
10Query.from(Article.class)
11    .where("title = ? and author = ?", "Getting Started", author);

and - Add AND Conditions

Chain additional conditions with AND:

1Query.from(Article.class)
2    .where("publishDate > ?", cutoffDate)
3    .and("author/name = ?", "John Doe")
4    .and("tags = ?", "java");

or - Add OR Conditions

Chain conditions with OR:

1Query.from(Article.class)
2    .where("author/name = ?", "John Doe")
3    .or("author/name = ?", "Jane Smith");

Complex combinations:

1// (publishDate > cutoff) OR (featured = true AND author = john)
2Query.from(Article.class)
3    .where("publishDate > ?", cutoffDate)
4    .or("featured = ? and author = ?", true, john);

not - Negate Conditions

1// Articles NOT by John Doe
2Query.from(Article.class)
3    .where("author/name != ?", "John Doe");
4
5// Or using not()
6Query.from(Article.class)
7    .not("author/name = ?", "John Doe");

having - Filter Grouped Results

Use having for filtering grouped queries:

1// Find authors with more than 5 articles
2Query.from(Article.class)
3    .groupBy("author")
4    .having("_count > ?", 5);

Predicate Operators

Equality Operators

1// Equals
2.where("status = ?", "published")
3
4// Not equals
5.where("status != ?", "draft")
6
7// Null/missing check
8.where("deletedDate = missing")
9.where("deletedDate != missing")

Comparison Operators

1// Greater than
2.where("publishDate > ?", date)
3
4// Greater than or equal
5.where("publishDate >= ?", date)
6
7// Less than
8.where("publishDate < ?", date)
9
10// Less than or equal
11.where("publishDate <= ?", date)

String Operators

1// Starts with
2.where("title ^= ?", "Getting")
3
4// Contains
5.where("content contains ?", "database")

Collection Operators

1// Contains any of the values
2.where("tags = ?", Arrays.asList("java", "database"))
3
4// Contains all values
5.where("tags = ?", tag1)
6.and("tags = ?", tag2)  // Both tags must be present

Range Queries

1// Between dates
2.where("publishDate > ? and publishDate < ?", startDate, endDate)

Full-Text Search

1// Search across all indexed fields
2.where("_any matches ?", "search terms")
3
4// Search specific field
5.where("content matches ?", "search terms")

Special Field Keys

_id - Object ID

1// Single ID
2.where("_id = ?", articleId)
3
4// Multiple IDs
5.where("_id = ?", Arrays.asList(id1, id2, id3))

_type - Object Type

1// Specific type
2.where("_type = ?", Article.class)
3
4// Type ID
5.where("_type = ?", ObjectType.getInstance(Article.class).getId())

_any - Search All Fields

1// Full-text search across all indexed fields
2.where("_any matches ?", "search query")

_label - Display Label

1// Search by label (calls getLabel())
2.where("_label matches ?", "Article")

Path-Based Field Access

Query nested fields using path notation:

1// Author's name
2.where("author/name = ?", "John Doe")
3
4// Nested objects
5.where("author/company/name = ?", "Acme Corp")
6
7// Collection items
8.where("comments/author/name = ?", "Jane Smith")
9
10// Map values
11.where("metadata/category = ?", "technology")

Sorting

sortAscending

1Query.from(Article.class)
2    .sortAscending("title");
3
4// Multiple fields
5Query.from(Article.class)
6    .sortAscending("author/name")
7    .sortAscending("publishDate");

sortDescending

1Query.from(Article.class)
2    .sortDescending("publishDate");

Sort by Relevance

Sort by relevance to a predicate (requires search-capable database):

1Query.from(Article.class)
2    .where("_any matches ?", "java database")
3    .sortRelevant(100, "_any matches ?", "java database");

Sort by Newest/Oldest

1// Newest first
2Query.from(Article.class)
3    .sortNewest(100, "publishDate");
4
5// Oldest first
6Query.from(Article.class)
7    .sortOldest(100, "publishDate");

Multiple Sort Criteria

1Query.from(Article.class)
2    .sortDescending("featured")      // Featured articles first
3    .sortDescending("publishDate")   // Then by date
4    .sortAscending("title");         // Then by title

Query Execution

selectAll

Execute query and return all results:

1List<Article> articles = Query.from(Article.class)
2    .where("publishDate > ?", cutoffDate)
3    .selectAll();

select (Pagination)

Execute with offset and limit:

1// First page (items 0-9)
2List<Article> page1 = Query.from(Article.class)
3    .sortDescending("publishDate")
4    .select(0, 10);
5
6// Second page (items 10-19)
7List<Article> page2 = Query.from(Article.class)
8    .sortDescending("publishDate")
9    .select(10, 10);
10
11// Calculate offset from page number
12int page = 3;
13int pageSize = 10;
14int offset = (page - 1) * pageSize;
15List<Article> pageN = query.select(offset, pageSize);

first

Get the first result (or null):

1Article article = Query.from(Article.class)
2    .where("slug = ?", "getting-started")
3    .first();
4
5if (article == null) {
6    // Not found
7}

findFirst (Optional)

Get the first result as an Optional:

1Optional<Article> optional = Query.from(Article.class)
2    .where("slug = ?", "getting-started")
3    .findFirst();
4
5optional.ifPresent(article -> {
6    System.out.println("Found: " + article.getTitle());
7});
8
9// Or with default
10Article article = Query.from(Article.class)
11    .where("slug = ?", "getting-started")
12    .findFirst()
13    .orElse(defaultArticle);

count

Count matching objects:

1long total = Query.from(Article.class).count();
2
3long published = Query.from(Article.class)
4    .where("publishDate != missing")
5    .count();

iterable

Get a streaming iterable for large result sets:

1Query<Article> query = Query.from(Article.class)
2    .where("publishDate > ?", cutoffDate);
3
4for (Article article : query.iterable(100)) {  // Fetch size 100
5    // Process each article
6    // Memory efficient for large datasets
7}

deleteAll

Delete all matching objects:

1// Delete old draft articles
2long deletedCount = Query.from(Article.class)
3    .where("status = ? and createdDate < ?", "draft", cutoffDate)
4    .deleteAll();
5
6System.out.println("Deleted " + deletedCount + " drafts");

Grouping and Aggregation

groupBy

Group results by one or more fields:

1// Group by author
2List<Grouping<Article>> byAuthor = Query.from(Article.class)
3    .groupBy("author")
4    .selectAll();  // Returns List<Grouping<Article>>
5
6for (Grouping<Article> group : byAuthor) {
7    Author author = (Author) group.getKeys().get(0);
8    long count = group.getCount();
9    System.out.println(author.getName() + ": " + count + " articles");
10}

1// Group by multiple fields
2List<Grouping<Article>> groups = Query.from(Article.class)
3    .groupBy("author", "publishYear")
4    .selectAll();
5
6for (Grouping<Article> group : groups) {
7    Author author = (Author) group.getKeys().get(0);
8    Integer year = (Integer) group.getKeys().get(1);
9    long count = group.getCount();
10    System.out.println(author.getName() + " in " + year + ": " + count);
11}

Filtering Grouped Results

1// Authors with more than 5 articles
2List<Grouping<Article>> prolificAuthors = Query.from(Article.class)
3    .groupBy("author")
4    .having("_count > ?", 5)
5    .selectAll();

Aggregation Functions

1// Get count for each group
2for (Grouping<Article> group : groups) {
3    long count = group.getCount();
4    // Use count...
5}
6
7// Access first item in group
8for (Grouping<Article> group : groups) {
9    Article firstArticle = group.getFirst();
10    // Use firstArticle...
11}
12
13// Get all items in group
14for (Grouping<Article> group : groups) {
15    List<Article> articles = group.getItems();
16    // Process all articles in this group...
17}

Query Modifiers

timeout

Set query timeout in seconds:

1Query.from(Article.class)
2    .timeout(30.0)  // 30 second timeout
3    .selectAll();

noCache

Bypass query result cache:

1Query.from(Article.class)
2    .noCache()
3    .selectAll();

master

Execute on master/primary database (force read from write source):

1// Ensure we read from master, not replica
2Query.from(Article.class)
3    .master()
4    .where("_id = ?", articleId)
5    .first();

Useful when:

You just wrote data and need to read it immediately
Avoiding replication lag
Critical reads that must be up-to-date

resolveToReferenceOnly

Load only reference information, not full objects:

1List<Article> refs = Query.from(Article.class)
2    .resolveToReferenceOnly()
3    .selectAll();
4
5// refs contains lightweight reference objects
6// Good for getting IDs, types, but not full data

resolveInvisible

Include records marked as invisible:

1Query.from(Article.class)
2    .resolveInvisible()
3    .selectAll();

option

Set database-specific options:

1Query.from(Article.class)
2    .option("hint", "USE INDEX (idx_author)")  // SQL hint
3    .option("readPreference", "secondary")     // MongoDB option
4    .selectAll();

comment

Add an informational comment to the query:

1Query.from(Article.class)
2    .comment("Dashboard recent articles widget")
3    .selectAll();

Useful for:

Debugging slow queries
Monitoring and logging
Tracking query origins in database logs

Subqueries

Use queries as predicate values for powerful filtering:

1// Find articles by authors in California
2Query<Article> articles = Query.from(Article.class)
3    .where("author = ?",
4        Query.from(Author.class)
5            .where("state = ?", "CA")
6    )
7    .selectAll();

1// Find articles NOT by specific authors
2Query<Article> articles = Query.from(Article.class)
3    .where("author != ?",
4        Query.from(Author.class)
5            .where("blacklisted = ?", true)
6    )
7    .selectAll();

1// Complex subquery
2Query<Article> articles = Query.from(Article.class)
3    .where("author = ?",
4        Query.from(Author.class)
5            .where("company = ?",
6                Query.from(Company.class)
7                    .where("name = ?", "Acme Corp")
8            )
9    )
10    .selectAll();

Practical Examples

Search with Filters

1public List<Article> searchArticles(String query, Author author,
2                                     Date startDate, Date endDate,
3                                     int page, int pageSize) {
4    Query<Article> q = Query.from(Article.class);
5
6    // Full-text search
7    if (query != null && !query.isEmpty()) {
8        q.where("_any matches ?", query);
9    }
10
11    // Filter by author
12    if (author != null) {
13        q.and("author = ?", author);
14    }
15
16    // Date range
17    if (startDate != null) {
18        q.and("publishDate >= ?", startDate);
19    }
20    if (endDate != null) {
21        q.and("publishDate <= ?", endDate);
22    }
23
24    // Pagination
25    int offset = (page - 1) * pageSize;
26    return q.sortDescending("publishDate")
27            .select(offset, pageSize);
28}

Dynamic Query Building

1public List<Article> findArticles(Map<String, Object> filters) {
2    Query<Article> query = Query.from(Article.class);
3    boolean first = true;
4
5    for (Map.Entry<String, Object> entry : filters.entrySet()) {
6        String field = entry.getKey();
7        Object value = entry.getValue();
8
9        query.and(field + " = ?", value);
10    }
11
12    return query.selectAll();
13}

1public List<Article> findRelatedArticles(Article article, int limit) {
2    // Find articles with overlapping tags, same author, or similar title
3    return Query.from(Article.class)
4        .where("_id != ?", article.getId())  // Exclude current article
5        .and("tags = ?", article.getTags())  // Matching tags
6        .or("author = ?", article.getAuthor())  // Same author
7        .sortDescending("publishDate")
8        .select(0, limit);
9}

Faceted Search

1public class SearchResult {
2    private List<Article> articles;
3    private Map<String, Long> authorCounts;
4    private Map<String, Long> tagCounts;
5
6    public static SearchResult search(String searchQuery) {
7        Query<Article> baseQuery = Query.from(Article.class)
8            .where("_any matches ?", searchQuery);
9
10        // Get articles
11        List<Article> articles = baseQuery
12            .sortRelevant(100, "_any matches ?", searchQuery)
13            .select(0, 20);
14
15        // Get author facets
16        Map<String, Long> authorCounts = new HashMap<>();
17        List<Grouping<Article>> authorGroups = baseQuery
18            .groupBy("author")
19            .selectAll();
20        for (Grouping<Article> group : authorGroups) {
21            Author author = (Author) group.getKeys().get(0);
22            authorCounts.put(author.getName(), group.getCount());
23        }
24
25        // Get tag facets
26        Map<String, Long> tagCounts = new HashMap<>();
27        List<Grouping<Article>> tagGroups = baseQuery
28            .groupBy("tags")
29            .selectAll();
30        for (Grouping<Article> group : tagGroups) {
31            String tag = (String) group.getKeys().get(0);
32            tagCounts.put(tag, group.getCount());
33        }
34
35        SearchResult result = new SearchResult();
36        result.articles = articles;
37        result.authorCounts = authorCounts;
38        result.tagCounts = tagCounts;
39        return result;
40    }
41}

Advanced Filtering

1public List<Article> findFeaturedOrRecent(Date cutoffDate) {
2    // Articles that are either featured OR published recently
3    return Query.from(Article.class)
4        .where("featured = ?", true)
5        .or("publishDate > ?", cutoffDate)
6        .sortDescending("publishDate")
7        .selectAll();
8}
9
10public List<Article> findByMultipleTags(List<String> tags) {
11    // Articles that have ALL specified tags
12    Query<Article> query = Query.from(Article.class);
13    for (String tag : tags) {
14        query.and("tags = ?", tag);
15    }
16    return query.selectAll();
17}
18
19public List<Article> findByAnyTag(List<String> tags) {
20    // Articles that have ANY of the specified tags
21    return Query.from(Article.class)
22        .where("tags = ?", tags)
23        .selectAll();
24}

Count by Category

1public Map<String, Long> countByCategory() {
2    Map<String, Long> counts = new LinkedHashMap<>();
3
4    List<Grouping<Article>> groups = Query.from(Article.class)
5        .groupBy("category")
6        .sortDescending("_count")
7        .selectAll();
8
9    for (Grouping<Article> group : groups) {
10        String category = (String) group.getKeys().get(0);
11        counts.put(category, group.getCount());
12    }
13
14    return counts;
15}

Find Duplicates

1public List<List<Article>> findDuplicateTitles() {
2    List<List<Article>> duplicates = new ArrayList<>();
3
4    // Group by title
5    List<Grouping<Article>> groups = Query.from(Article.class)
6        .groupBy("title")
7        .having("_count > ?", 1)  // Only groups with more than 1
8        .selectAll();
9
10    for (Grouping<Article> group : groups) {
11        // Get all articles with this title
12        String title = (String) group.getKeys().get(0);
13        List<Article> dupes = Query.from(Article.class)
14            .where("title = ?", title)
15            .selectAll();
16        duplicates.add(dupes);
17    }
18
19    return duplicates;
20}

Performance Tips

Index Your Query Fields

1// Ensure queried fields are indexed
2@Indexed
3private String title;
4
5@Indexed
6private Date publishDate;
7
8@Indexed
9private Author author;

Use Pagination

1// Good - loads 10 items
2query.select(0, 10);
3
4// Bad - loads everything
5query.selectAll();

Use count() Instead of Loading All

1// Good
2long count = query.count();
3
4// Bad
5long count = query.selectAll().size();

Use Specific Predicates

1// Good - uses index efficiently
2.where("publishDate > ?", cutoffDate)
3
4// Less efficient - may scan more rows
5.where("publishDate != missing")

Common Pitfalls

Forgetting to Index

1// This will fail if 'title' is not indexed
2Query.from(Article.class)
3    .where("title = ?", "Getting Started")
4    .selectAll();
5// ERROR: Field 'title' is not indexed

Loading Too Much Data

1// Avoid loading thousands of objects at once
2List<Article> all = Query.from(Article.class).selectAll();
3// Use pagination or iterable() instead

Inefficient Filtering

1// Bad - loads everything then filters in memory
2List<Article> all = Query.from(Article.class).selectAll();
3List<Article> filtered = all.stream()
4    .filter(a -> a.getPublishDate().after(cutoffDate))
5    .collect(Collectors.toList());
6
7// Good - filters at database level
8List<Article> filtered = Query.from(Article.class)
9    .where("publishDate > ?", cutoffDate)
10    .selectAll();

Not Handling Null Results

1// Bad - can throw NullPointerException
2Article article = Query.from(Article.class)
3    .where("_id = ?", id)
4    .first();
5String title = article.getTitle();  // NPE if article is null
6
7// Good - check for null
8Article article = Query.from(Article.class)
9    .where("_id = ?", id)
10    .first();
11if (article != null) {
12    String title = article.getTitle();
13}
14
15// Or use Optional
16Query.from(Article.class)
17    .where("_id = ?", id)
18    .findFirst()
19    .map(Article::getTitle)
20    .orElse("Untitled");

Query Construction​

Basic Factory Methods​

Using a Specific Database​

Predicates and Filtering​

where - Initial Predicate​

and - Add AND Conditions​

or - Add OR Conditions​

not - Negate Conditions​

having - Filter Grouped Results​

Predicate Operators​

Equality Operators​

Comparison Operators​

String Operators​

Collection Operators​

Range Queries​

Full-Text Search​

Special Field Keys​

_id - Object ID​

_type - Object Type​

_any - Search All Fields​

_label - Display Label​

Path-Based Field Access​

Sorting​

sortAscending​

sortDescending​

Sort by Relevance​

Sort by Newest/Oldest​

Multiple Sort Criteria​

Query Execution​

selectAll​

select (Pagination)​

first​

findFirst (Optional)​

count​

iterable​

deleteAll​

Grouping and Aggregation​

groupBy​

Filtering Grouped Results​

Aggregation Functions​

Query Modifiers​

timeout​

noCache​

master​

resolveToReferenceOnly​

resolveInvisible​

option​

comment​

Subqueries​

Practical Examples​

Search with Filters​

Dynamic Query Building​

Related Content​

Faceted Search​

Advanced Filtering​

Count by Category​

Find Duplicates​

Performance Tips​

Index Your Query Fields​

Use Pagination​

Use count() Instead of Loading All​

Use Specific Predicates​

Common Pitfalls​

Forgetting to Index​

Loading Too Much Data​

Inefficient Filtering​

Not Handling Null Results​