Help

list Method - Service Factory Reference

This method of a module's service retrieves a list of records.

The method's name is listDataModel, where DataModel is the plural pascal-case name of the data model.

Retrieve List of Records#

Code
const posts = await postModuleService.listPosts()

If no parameters are passed, the method returns all matching records.

Warning: When you call this method directly from a workflow step or a custom route handler without passing a take value, it returns all records from the database without any limit. Pass the take parameter to avoid unbounded fetches on large tables.The default limit of 50 records is enforced by the HTTP query-config middleware layer, not by the module service method itself. It only applies when the method is called through Medusa's built-in HTTP routes.

Filter Records#

Code
1const posts = await postModuleService.listPosts({2  id: ["123", "321"],3})

Parameters#

To retrieve records matching a set of filters, pass an object of the filters as the first parameter.

Note: Refer to the Filtering reference for more information on accepted filters and examples.

Returns#

The method returns an array of all records matching the filters.

Retrieve Relations#

Note: This applies to relations between data models of the same module. To retrieve linked records of different modules, use Query.

Code
1const posts = await postModuleService.listPosts({}, {2  relations: ["author"],3})

Parameters#

To retrieve records with their relations, pass an object with a relations property as the second parameter. relations's value is an array of relation names.

Returns#

The method returns an array of all records matching the filters.

Select Properties#

Code
1const posts = await postModuleService.listPosts({}, {2  select: ["id", "name"],3})

Parameters#

By default, retrieved records have all their properties. To select specific properties to retrieve, pass a select property in the second object parameter.

select's value is an array of property names to retrieve.

Returns#

The method returns an array of all records matching the filters.

Paginate Records#

Code
1const posts = await postModuleService.listPosts({}, {2  take: 20,3  skip: 10,4})

Parameters#

To paginate the returned records, the second object parameter accepts the following properties:

take: a number indicating how many records to retrieve. When not specified, all matching records are returned.
skip: a number indicating how many records to skip before the retrieved records. By default, it's 0.

Returns#

The method returns an array of records. The number of records is less than or equal to take's value.

Sort Records#

Code
1const posts = await postModuleService.listPosts({}, {2  order: {3    name: "ASC",4  },5})

Parameters#

To sort records by one or more properties, pass an order property in the second object parameter. Its value is an object whose keys are the property names, and values can either be:

ASC to sort by this property in the ascending order.
DESC to sort by this property in the descending order.

Returns#

The method returns an array of all records matching the filters.

Was this page helpful?