docs: documet withDeleted (#12841)

* docs: documet withDeleted * fixes * small fix
2025-06-26 19:35:53 +03:00
1 parent 035ef9e4c9
commit f77696e14b
@@ -71,6 +71,35 @@ The method returns an object that has a `data` property, which holds an array of
 }
 ```

+### Query Usage in Workflows
+
+To retrieve data with Query in a [workflow](../../workflows/page.mdx), use the [useQueryGraphStep](!resources!/references/helper-steps/useQueryGraphStep).
+
+For example:
+
+```ts title="src/workflows/query.ts"
+import { createWorkflow, WorkflowResponse } from "@medusajs/framework/workflows-sdk"
+import { useQueryGraphStep } from "@medusajs/medusa/core-flows"
+
+const myWorkflow = createWorkflow(
+  "my-workflow",
+  () => {
+    const { data: posts } = useQueryGraphStep({
+      entity: "post",
+      fields: ["id", "title"],
+    })
+
+    return new WorkflowResponse({
+      posts,
+    })
+  }
+)
+```
+
+You can learn more about this step in the [useQueryGraphStep](!resources!/references/helper-steps/useQueryGraphStep) reference.
+
+The rest of this chapter uses the `graph` method to explain the different usages of Query, but the same principles apply to `useQueryGraphStep`.
+
 ---

 ## Querying the Graph
@@ -98,7 +127,7 @@ const { data: posts } = await query.graph({
 })
 ```

-`.*` means that all of data model's properties should be retrieved. You can also retrieve specific properties by replacing the `*` with the property name, for each property.
+`.*` means that all of the data model's properties should be retrieved. You can also retrieve specific properties by replacing the `*` with the property name for each property.

 For example:

@@ -137,7 +166,7 @@ In the example above, you retrieve all products linked to a post.

 ### Apply Filters and Pagination on Linked Records

-Consider you want to apply filters or pagination configurations on the product(s) linked to `post`. To do that, you must query the module link's table instead.
+Consider that you want to apply filters or pagination configurations on the product(s) linked to a `post`. To do that, you must query the module link's table instead.

 As mentioned in the [Module Link](../page.mdx) documentation, Medusa creates a table for your module link. So, not only can you retrieve linked records, but you can also retrieve the records in a module link's table.

@@ -170,7 +199,7 @@ const { data: productCustoms } = await query.graph({
 In the object passed to the `graph` method:

 - You pass the `entryPoint` property of the link definition as the value for `entity`. So, Query will retrieve records from the module link's table.
- You pass three items to the `field` property:
+- You pass three items to the `fields` property:
    - `*` to retrieve the link table's fields. This is useful if the link table has [custom columns](../custom-columns/page.mdx).
    - `product.*` to retrieve the fields of a product record linked to a `Post` record.
    - `post.*` to retrieve the fields of a `Post` record linked to a product record.
@@ -243,7 +272,7 @@ Under the hood, Query uses one of the following methods from the data model's mo
 - `listX` if you don't pass [pagination parameters](#apply-pagination). For example, `listPosts`.
 - `listAndCountX` if you pass pagination parameters. For example, `listAndCountPosts`.

-Both methods accepts a filter object that can be used to filter records.
+Both methods accept a filter object that can be used to filter records.

 Those filters don't just allow you to filter by exact values. You can also filter by properties that don't match a value, match multiple values, and other filter types.

@@ -418,9 +447,57 @@ The `order` property is an object whose keys are property names, and values are

 ---

+## Retrieve Deleted Records
+
+By default, Query doesn't retrieve deleted records. To retrieve all records including deleted records, you can pass the `withDeleted` property to the `query.graph` method.
+
+<Note>
+
+The `withDeleted` property is available from [Medusa v2.8.5](https://github.com/medusajs/medusa/releases/tag/v2.8.5).
+
+</Note>
+
+For example:
+
+```ts highlights={[["4", "withDeleted", "Include deleted posts in the results."]]}
+const { data: posts } = await query.graph({
+  entity: "post",
+  fields: ["id", "title"],
+  withDeleted: true,
+})
+```
+
+In the example above, you retrieve all posts, including deleted ones.
+
+### Retrieve Only Deleted Records
+
+To retrieve only deleted records, you can add a `deleted_at` filter and set its value to not `null`. For example:
+
+export const withDeletedHighlights = [
+  ["5", "deleted_at", "Filter to retrieve posts whose `deleted_at` property is not `null`."],
+  ["9", "withDeleted", "Include deleted posts in the results."],
+]
+
+```ts highlights={withDeletedHighlights}
+const { data: posts } = await query.graph({
+  entity: "post",
+  fields: ["id", "title"],
+  filters: {
+    deleted_at: {
+      $ne: null,
+    },
+  },
+  withDeleted: true,
+})
+```
+
+In the example above, you retrieve only deleted posts by enabling the `withDeleted` property and adding a filter to only retrieve records where the `deleted_at` property is not `null`.
+
+---
+
 ## Configure Query to Throw Errors

-By default, if Query doesn't find records matching your query, it returns an empty array. You can add option to configure Query to throw an error when no records are found.
+By default, if Query doesn't find records matching your query, it returns an empty array. You can add an option to configure Query to throw an error when no records are found.

 The `query.graph` method accepts as a second parameter an object that can have a `throwIfKeyNotFound` property. Its value is a boolean indicating whether to throw an error if no record is found when filtering by IDs. By default, it's `false`.

@@ -459,7 +536,7 @@ const { data: posts } = await query.graph({
 })
 ```

-In the example above, Query throws an error either if no post is found with the ID `post_123` or if its found but its author ID isn't `author_123`.
+In the example above, Query throws an error either if no post is found with the ID `post_123` or if it's found but its author ID isn't `author_123`.

 In the above example, it's assumed that a post belongs to an author, so it has an `author_id` property. However, this also works in the opposite case, where an author has many posts.

@@ -538,7 +615,7 @@ The `validateAndTransformQuery` accepts two parameters:
    4. `order`: The fields to order the returned items by in ascending or descending order.
 2. A Query configuration object. It accepts the following properties:
    1. `defaults`: An array of default fields and relations to retrieve in each resource.
-    2. `isList`: A boolean indicating whether a list of items are returned in the response.
+    2. `isList`: A boolean indicating whether a list of items is returned in the response.
    3. `allowed`: An array of fields and relations allowed to be passed in the `fields` query parameter.
    4. `defaultLimit`: A number indicating the default limit to use if no limit is provided. By default, it's `50`.

@@ -554,7 +631,7 @@ As of [Medusa v2.2.0](https://github.com/medusajs/medusa/releases/tag/v2.2.0), `

 </Note>

-For example, Create the file `src/api/customs/route.ts` with the following content:
+For example, create the file `src/api/customs/route.ts` with the following content:

 export const queryConfigHighlights = [
  ["17", "req.queryConfig", "Pass the parsed request Query configurations to the Query graph execution."]
@@ -590,7 +667,7 @@ In the API route, you pass `req.queryConfig` to `query.graph`. `queryConfig` has

 ### Test it Out

-To test it out, start your Medusa application and send a `GET` request to the `/customs` API route. A list of records are retrieved with the specified fields in the middleware.
+To test it out, start your Medusa application and send a `GET` request to the `/customs` API route. A list of records is retrieved with the specified fields in the middleware.

 ```json title="Returned Data"
 {
@@ -607,6 +684,6 @@ Try passing one of the Query configuration parameters, like `fields` or `limit`,

 <Note>

-Learn more about [specifing fields and relations](!api!/store#select-fields-and-relations) and [pagination](!api!/store#pagination) in the API reference.
+Learn more about [specifying fields and relations](!api!/store#select-fields-and-relations) and [pagination](!api!/store#pagination) in the API reference.

 </Note>