> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

# Method name: query(collectionId: string)

# Method package: wixData

# Method menu location: wixData --> query

# Method Link: https://dev.wix.com/docs/velo/apis/wix-data/query.md

# Method Description:

Creates a query for retrieving items from a database collection.

The `query()` function builds a query on the specified collection and returns
 a [`WixDataQuery`](https://dev.wix.com/docs/velo/api-reference/wix-data/wix-data-query/introduction.md) object.

 The returned object contains the query definition which is typically used
 to run the query using the [`find()`](wix-data.WixDataQuery.html#find)
 function.

 You can refine the query by chaining [`WixDataQuery`](https://dev.wix.com/docs/velo/api-reference/wix-data/wix-data-query/introduction.md)
 functions onto the query. `WixDataQuery` functions enable you to sort,
 filter, and control the results a query returns.

 The `query()` runs with the following [`WixDataQuery`](https://dev.wix.com/docs/velo/api-reference/wix-data/wix-data-query/introduction.md)
 defaults that you can override:

 + [`skip`](wix-data.WixDataQuery.html#skip): `0`
 + [`limit`](wix-data.WixDataQuery.html#limit): `50`
 + [`descending`](wix-data.WixDataQuery.html#descending): by `_createdDate`
 + [`include`](wix-data.WixDataQuery.html#include): none



 The functions that are chained to `query()` are applied in the order they
 are called. For example, if you sort on an `age` property in ascending
 order and then on a `name` property in descending order, the results are
 sorted first by the age of the items and then, if there are multiple
 results with the same age, the items are sorted by name in descending
 order, per age value.


If the collection that you are querying has references to other collections, by default, the data from referenced collections will not be retrieved. To get the data from the referenced items, you must either use the [`include()`](wix-data.WixDataQuery.html#include) chained function before `find()` or use the [`queryReferenced()`](https://dev.wix.com/docs/velo/api-reference/wix-data/query-referenced.md) function instead of `query()`.

Items marked as hidden in the collection are not returned.

When working with [Wix app collections](https://support.wix.com/en/article/velo-working-with-wix-app-collections-and-code), fields in the collections have the following permissions:
 + Can connect to data
 + Can use in dynamic page URL
 + Can be sorted
 + Can be filtered
 + Read-only
Check [which fields](https://support.wix.com/en/search?term=velo%20collection%20fields) can be used in a query.

 > **Notes:**
 > - When using the `query()` or `get()` functions or another data retrieval method following a change to your database collection, the data retrieved may not contain your most recent changes. See [Wix Data and Eventual Consistency]https://dev.wix.com/docs/velo/api-reference/wix-data/introduction.md#api-reference_wix-data_wix-data-and-eventual-consistency) for more information. To solve this problem, you can use the [`setTimeout()`](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Asynchronous/Timeouts_and_intervals#setTimeout) function to delay retrieving data following any changes to your database collection.
> - To speed up data retrieval, the results of certain data queries are cached. Learn more about [caching data query results](https://dev.wix.com/docs/develop-websites/articles/databases/wix-data/data-api/about-caching-data-query-results.md).
 > **Note:**
 When using the `query()` or `get()` functions or another data retrieval method following a change to your database collection, the data retrieved may not contain your most recent changes. See [Wix Data and Eventual Consistency](https://dev.wix.com/docs/velo/api-reference/wix-data-v2/eventual-consistency.md) for more information. To solve this problem, you can use the [`setTimeout()`](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Asynchronous/Timeouts_and_intervals#setTimeout) function to delay retrieving data following any changes to your database collection.
 > - To speed up data retrieval, the results of certain data requests are cached. Learn more about [caching data query results](https://dev.wix.com/docs/develop-websites/articles/databases/wix-data/data-api/about-caching-data-query-results.md).



# Method Code Examples:

*** Note: do not assume any prop names or enum values other than the ones in the example.

## Build a query

```javascript
import wixData from 'wix-data';

// ...

let query = wixData.query("myCollection");
```

## Build and perform a query

```javascript
import wixData from 'wix-data';

// ...

wixData.query("myCollection")
  .find()
  .then((results) => {
    if(results.items.length > 0) {
      console.log(results.items[0]); //see item below
    } else {
      // handle case where no matching items found
    }
  })
  .catch((err) => {
    console.log(err);
  });

/*  firstItem is:
 *
 *  {
 *    "_id":          "00001",
 *    "_owner":       "ffdkj9c2-df8g-f9ke-lk98-4kjhfr89keedb",
 *    "_createdDate": "2017-05-24T12:33:18.938Z",
 *    "_updatedDate": "2017-05-24T12:33:18.938Z",
 *    "title":        "Mr.",
 *    "first_name":   "John",
 *    "last_name":    "Doe"
 *  }
 */
```

## Build and perform a query using data options

```javascript
import wixData from 'wix-data';

// ...

wixData.query("myCollection")
  .eq("title", "Dr.")
  .find()
  .then((results) => {
    if(results.items.length > 0) {
      console.log(results.items[0]); //see firstItem below
    } else {
      // handle case where no matching items found
    }
  })
  .catch((err) => {
    console.log(err);
  });

/*  firstItem is:
 *
 *  {
 *    "_id":          "00002",
 *    "_owner":       "ffdkj9c2-df8g-f9ke-lk98-4kjhfr89keedb",
 *    "_createdDate": "2017-05-24T12:33:18.938Z",
 *    "_updatedDate": "2017-05-24T12:33:18.938Z",
 *    "title":        "Dr.",
 *    "first_name":   "Jane",
 *    "last_name":    "Doe"
 *  }
 */
```

## Create, filter, sort, limit, and run a query

```javascript
import wixData from 'wix-data';

// ...

wixData.query("myCollection")
  .eq("status", "active")
  .gt("age", 25)
  .ascending("last_name", "first_name")
  .limit(10)
  .find()
  .then((results) => {
    if(results.items.length > 0) {
      let items = results.items;
      let firstItem = items[0];
      let totalCount = results.totalCount;
      let pageSize = results.pageSize;
      let currentPage = results.currentPage;
      let totalPages = results.totalPages;
      let hasNext = results.hasNext();
      let hasPrev = results.hasPrev();
      let length = results.length;
      let query = results.query;
    } else {
      // handle case where no matching items found
    }
  })
  .catch((error) => {
    let errorMsg = error.message;
    let code = error.code;
  });
```

## Build a query incrementally

```javascript
import wixData from 'wix-data';

// ...

function runQuery(low, high) {
  let myQuery = wixData.query("myCollection");

  if(low) {
    myQuery = myQuery.ge("price", low);
  }

  if(high) {
    myQuery = myQuery.le("price", high);
  }

  myQuery.find()
    .then((results) => {
      if(results.items.length > 0) {
        $w("#myTable").rows = results.items;
      } else {
        $w("#myTable").collapse();
      }
    });
}

```

## Build a query using `include()` to include the referenced collection cities, based on the field "city" from myCollection

```javascript
import wixData from 'wix-data';

wixData.query("myCollection")
  .include("city")
  .find()
  .then((results) => {
    let firstItem = results.items[0]
    console.log(firstItem);
  });


 /*  firstItem is:
  *
  *   {
  *     "_id":            "1d8a1d97-93d3-4d6c-9a0f-c279058b4aa5",
  *     "_owner":         "81c9168e-95b8-47fd-8e6a-ad9fdf71b38e",
  *     "_createdDate":   "2020-08-03T10:26:26.825Z",
  *     "_updatedDate":   "2020-08-03T10:27:01.558Z",
  *     "first_name":     "Betty",
  *     "last_name":      "Boop",
  *     "city": 
  *            {
  *              "_id":            "a99daca6-0400-4ef1-8d74-de3f9095bf0b",
  *              "_owner":         "81c9168e-95b8-47fd-8e6a-ad9fdf71b38e",
  *              "_createdDate":   "2020-08-03T10:22:39.114Z",
  *              "_updatedDate":   "2020-08-03T10:23:25.042Z" ,
  *              "city_name":      "Los Angeles",
  *              "state":          "California"
  *       }
  */
```

## Query a collection using a custom function

```javascript
import wixData from 'wix-data';

// Code for a read operation using query() //

async function readGreetings() {
  const results = await wixData.query('Greetings').ascending('language').find();

  return results.items;
}

```

---