You are currently browsing legacy 3.0 version of documentation. Click here to switch to the newest 4.2 version.

We can help you with migration to the latest RavenDB

Contact Us Now
see on GitHub

Commands: Querying: How to query a database?

Use Query method to fetch results of a selected index according to a specified query.

Syntax

curl \
	http://{serverName}/databases/{databaseName}/indexes/{indexName}? \
		&metadata-only={metadataOnly} \
		&include={include} \
		[Other indexQuery parameters] \
	-X GET

IndexQuery parameters

This endpoint accepts IndexQuery object. All possible IndexQuery parameters are listed here

IndexQuery parameters

The table below descibes allowed request parameters which can be passed as a part on IndexQuery.

Query parameter Required Allow multiple Default value Description
query no no "" Index query (in lucene syntax)
start no no 0 The start of records to read
cutoff no no null The cutoff date
waitForNonStaleResultsAsOfNow no no false the WaitForNonStaleResultsAsOfNow
cutOffEtag no no null Cutoff etag is used to check if the index has already process a document with the given etag. Unlike Cutoff, which uses dates and is susceptible to clock synchronization issues between machines, cutoff etag doesn't rely on both the server and client having a synchronized clock and can work without it. However, when used to query map/reduce indexes, it does NOT guarantee that the document that this etag belong to is actually considered for the results. What it does it guarantee that the document has been mapped, but not that the mapped values has been reduce. Since map/reduce queries, by their nature,tend to be far less susceptible to issues with staleness, this is considered to be an acceptable tradeoff. If you need absolute no staleness with a map/reduce index, you will need to ensure synchronized clocks and use the Cutoff date option, instead.
pageSize no no 25 The page size
fetch no yes null The fields names to fetch
defaultField no no null The default field to use when querying directly on the Lucene query
operator no no or Changes the default operator mode we use for queries. When set to Or a query such as 'Name:John Age:18' will be interpreted as: Name:John OR Age:18 When set to And the query will be interpreted as: Name:John AND Age:18
sort no yes null The sort fields by sort by
highlight no yes null The options to highlight the fields
preTags no yes null The highlighter pre tags
postTags no yes null The highlighter post tags
resultsTransformer no no null The results transformer
tp-{param}={value} no yes null Additional transformer parameters
explainScores no no false Whatever a query result should contains an explanation about how docs scored against query
SortHint-{param}={value} no yes null The sort hints
distinct no no false Whatever we should apply distinct operation to the query on the server side
allowMultiple IndexEntriesForSameDocument ToResultTransformer no no true If set to true, this property will send multiple index entries from the same document (assuming the index project them) to the result transformer function. Otherwise, those entries will be consolidate an the transformer will be called just once for each document in the result set
showTimings no no false Indicates if detailed timings should be calculated for various query parts (Lucene search, loading documents, transforming results)
spatialField no no __spatial Spatial field name
queryShape no no null Spatial query shape
spatialUnits no no Kilometers Spatial units
distErrPrc no no 0.025 Distance error percentage
spatialRelation no no null Spatial relation

Request

Query parameter Required Description
indexName Yes A name of an index to query
include No An array of relative paths that specify related documents ids which should be included in a query result.
metadataOnly No True if returned documents should include only metadata without a document body.

Response

Status code Description
200 OK
Return Value Description
Results List of requested documents
Includes List of included documents

Example I

A sample Query method call that returns orders for a company specified:

curl -X GET "http://localhost:8080/databases/NorthWind/indexes/Orders/Totals?&query=Company%3Acompanies%2F1&pageSize=128" 
< HTTP/1.1 200 OK
{"Results":[...results ...],"Includes":[]}

Example II

If a model of your documents is such that they reference others and you want to retrieve them together in a single query request, then you need to specify paths to properties that contain IDs of referenced documents:

curl -X GET "http://localhost:8080/databases/NorthWind/indexes/Orders/Totals?&pageSize=128&include=Company&include=Employee" 
< HTTP/1.1 200 OK
{"Results":[...results ...],"Includes":[... includes ...]}