See on GitHub

    Query Overview

    • PHP Queries can be written -

      • Using the session's query method
      • Using the session's documentQuery method
      • Using RQL:
        • via the session's rawQuery method
        • via the Studio's Query view

    • Queries defined using query or documentQuery are translated by the RavenDB client to RQL when sent to the server.

    • All RavenDB queries use an index to provide results, even when an index is not explicitly defined.
      Learn more below.

    • Queries that do Not specify which index to use are called Dynamic Queries.
      This article shows examples of dynamic queries only.
      For index query examples see querying an index.

    • The entities returned by the query are 'loaded' and tracked by the session.
      Entities will Not be tracked when:

    • Query results are cached by default.
      To disable query caching see NoCaching.

    • Queries are timed out after a configurable time period.
      See query timeout.

    Queries always provide results using an index

    • Queries always use an index to provide fast results regardless of the size of your data.

    • When a query reaches a RavenDB instance, the instance calls its query optimizer to analyze the query
      and determine which index should be used to retrieve the requested data.

    • Indexes allow to provide query results without scanning the entire dataset each and every time.

      • Learn more about indexes, their general concept, and the different index types in this indexes overview article.
      • You can choose the underlying search engine that will be used by the RavenDB indexes.
        Learn more in selecting the search engine.

    We differentiate between the following 3 query scenarios:

    1. Index query
    2. Dynamic query
    3. Full collection query

    For each scenario, a different index type is used, as described below.

    1. Query an existing index:

    • Query type: Index query
      Index used: Static-index

    • You can specify which STATIC-index the query will use.

    • Static indexes are defined by the user, as opposed to auto-indexes that are created by the server
      when querying a collection with some filtering applied. See Static-index vs Auto-index.

    • Example RQL:   from index "Employees/ByFirstName" where FirstName == "Laura"
      See more examples in querying an index.

    2. Query a collection - with filtering:

    • Query type: Dynamic Query
      Index used: Auto-index

    • When querying a collection without specifying an index and with some filtering condition
      (other than just the document ID) the query-optimizer will analyze the query to see if an AUTO-index
      that can answer the query already exists, i.e. an auto-index on the collection queried with index-fields that match those queried.

    • If such auto-index (Not a static one...) is found, it will be used to fetch the results.

    • Else, if no relevant auto-index is found,
      the query-optimizer will create a new auto-index with fields that match the query criteria.
      At this time, and only at this time, the query will wait for the auto-indexing process to complete.
      Subsequent queries that target this auto-index will be served immediately.

    • Note: if there exists an auto-index that is defined on the collection queried
      but is indexing a different field than the one queried on,
      then the query-optimizer will create a new auto-index that merges both the
      fields from the existing auto-index and the new fields queried.

    • Once the newly created auto-index is done indexing the data,
      the old auto-index is removed in favor of the new one.

    • Over time, an optimal set of indexes is generated by the query optimizer to answer your queries.

    • RQL Example:   from Employees where FirstName == "Laura"
      See more examples below.

    • Note: Counters and Time series are an exception to this flow.
      Dynamic queries on counters and time series values don't create auto-indexes.
      However, a static-index can be defined on Time series and Counters.

    3. Query a collection - query full collection | query by ID:

    • Query type: Full collection Query
      Index used: The raw collection (internal storage indexes)

    • Full collection query:

      • When querying a collection without specifying an index and with no filtering condition,
        then all documents from the specified collection are returned.

      • RavenDB uses the raw collection documents in its internal storage indexes as the source for this query.
        No auto-index is created.

      • Example RQL:   from Employees

    • Query by document ID:

      • When querying a collection only by document ID or IDs,
        then similar to the full collection query, no auto-index is created.

      • RavenDB uses the raw collection documents as the source for this query.

      • Example RQL:   from Employees where id() == "employees/1-A"
        See more examples below.

    session.query

    • The simplest way to issue a query is by using the session's query method which supports LINQ.
      Both the LINQ method syntax and the LINQ query syntax are supported.

    • The following examples show dynamic queries that do not specify which index to use.
      Please refer to querying an index for other examples.

    • Querying can be enhanced using these extension methods.

    Query collection - no filtering 

    // This is a Full Collection Query
// No auto-index is created since no filtering is applied

$allEmployees = $session
    ->query(Employee::class)  // Query for all documents from 'Employees' collection
    ->toList();                         // Execute the query

// All 'Employee' entities are loaded and will be tracked by the session
    // This RQL is a Full Collection Query
// No auto-index is created since no filtering is applied

from "Employees"

    Query collection - by ID

    // Query collection by document ID
// No auto-index is created when querying only by ID

$employee = $session
    ->query(Employee::class)
    ->whereEquals("Id", "employees/1-A") // Query for specific document from 'Employees' collection
    ->firstOrDefault();                                 // Execute the query

// The resulting 'Employee' entity is loaded and will be tracked by the session
    // This RQL queries the 'Employees' collection by ID
// No auto-index is created when querying only by ID

from "Employees" where id() == "employees/1-A"

    Query collection - with filtering 

    // Query collection - filter by document field

// An auto-index will be created if there isn't already an existing auto-index
// that indexes this document field

$employees = $session
    ->query(Employee::class)
    ->whereEquals("FirstName", "Robert") // Query for all 'Employee' documents that match this predicate
    ->ToList();                                         // Execute the query

// The resulting 'Employee' entities are loaded and will be tracked by the session
    // Query collection - filter by document field

// An auto-index will be created if there isn't already an existing auto-index
// that indexes the requested field

from "Employees" where FirstName == "Robert"

    Query collection - with paging 

    // Query collection - page results
// No auto-index is created since no filtering is applied

$products = $session
    ->query(Product::class)
    ->skip(5)   // Skip first 5 results
    ->take(10)  // Load up to 10 entities from 'Products' collection
    ->toList(); // Execute the query

// The resulting 'Product' entities are loaded and will be tracked by the session
    // Query collection - page results
// No auto-index is created since no filtering is applied

from "Products" limit 5, 10 // skip 5, take 10
    • By default, if the page size is not specified, all matching records will be retrieved from the database.

    session.advanced.documentQuery

    • documentQuery provides a full spectrum of low-level querying capabilities,
      giving you more flexibility and control when making complex queries.

    • Below is a simple DocumentQuery usage.
      For a full description and more examples see:

    Example:

    // Query with DocumentQuery - filter by document field

// An auto-index will be created if there isn't already an existing auto-index
// that indexes this document field

$employees = $session
    ->advanced()->documentQuery(Employee::class) // Use DocumentQuery
    ->whereEquals("FirstName", "Robert")    // Query for all 'Employee' documents that match this predicate
    ->toList();                                            // Execute the query

// The resulting 'Employee' entities are loaded and will be tracked by the session
    // Query collection - filter by document field

// An auto-index will be created if there isn't already an existing auto-index
// that indexes the requested field

from "Employees" where FirstName = "Robert"

    session.advanced.rawQuery

    • Queries defined with query or documentQuery are translated by the RavenDB client to RQL
      when sent to the server.

    • The session also gives you a way to express the query directly in RQL using the rawQuery method.

    Example:

    // Query with RawQuery - filter by document field

// An auto-index will be created if there isn't already an existing auto-index
// that indexes this document field

$employees = $session
    // Provide RQL to RawQuery
    ->advanced()->rawQuery(Employee::class, "from 'Employees' where FirstName = 'Robert'")
    // Execute the query
    ->toList();

// The resulting 'Employee' entities are loaded and will be tracked by the session

    Custom methods

    Available custom methods for session's query method:

    Syntax 

    // Methods for querying a collection OR an index:
// ================================================

public function query(?string $className, $collectionOrIndexName = null): DocumentQueryInterface;

public function documentQuery(?string $className, $indexNameOrClass = null, ?string $collectionName = null, bool $isMapReduce = false): DocumentQueryInterface;

// RawQuery:
// =========
public function rawQuery(?string $className, string $query): RawDocumentQueryInterface;
    Parameter Type Description
    $className string The name of the class to query
    $collectionOrIndexName ?string The name of the collection or index to query
    $indexNameOrClass ?string The name or class of the index to query
    $collectionName ?string The name of the collection to query
    $isMapReduce bool Whether querying a map-reduce index
    $query string The RQL query string
    Return Value
    DocumentQueryInterface
    RawDocumentQueryInterface    		 Interfaces exposing additional query methods and extensions

    related articlesRelated Articles

    Session

    Querying

    Indexes

    Home / Docs / Client Api / Session / Querying / How To Query