From 092170a2460afe2b7934f18decb6a502179c2e9e Mon Sep 17 00:00:00 2001
From: Taylor Ninesling <taylor.ninesling@apollographql.com>
Date: Wed, 21 Aug 2024 07:29:11 -0700
Subject: [PATCH] Add sections on using @cost and @listSize to demand control
 docs (#5839)

---
 .../docs_tninesling_cost_docs_update.md       |  5 ++
 .../executing-operations/demand-control.mdx   | 58 +++++++++++++++++++
 2 files changed, 63 insertions(+)
 create mode 100644 .changesets/docs_tninesling_cost_docs_update.md

diff --git a/.changesets/docs_tninesling_cost_docs_update.md b/.changesets/docs_tninesling_cost_docs_update.md
new file mode 100644
index 0000000000..7311bdfa38
--- /dev/null
+++ b/.changesets/docs_tninesling_cost_docs_update.md
@@ -0,0 +1,5 @@
+### Add sections on using @cost and @listSize to demand control docs ([PR #5839](https://github.com/apollographql/router/pull/5839))
+
+Updates the demand control documentation to include details on `@cost` and `@listSize` for more accurate cost estimation.
+
+By [@tninesling](https://github.com/tninesling) in https://github.com/apollographql/router/pull/5839
diff --git a/docs/source/executing-operations/demand-control.mdx b/docs/source/executing-operations/demand-control.mdx
index 8b441cb381..f2c5657a22 100644
--- a/docs/source/executing-operations/demand-control.mdx
+++ b/docs/source/executing-operations/demand-control.mdx
@@ -360,6 +360,21 @@ Looking at the top N operations, you may see that the estimated costs have been
 
 All operations except `ExtractAll` are in a range of acceptable costs.
 
+<MinVersion version="1.53.0">
+
+#### `@listSize`
+
+</MinVersion>
+
+If some of your fields have list sizes that significantly differ from `static_estimated.list_size`, you can provide the router with more information.
+
+The `@listSize` directive can be configured in multiple ways:
+
+1. Use the `assumedSize` argument to define a static size for a field.
+2. Use `slicingArguments` to indicate that a field's size is dynamically controlled by one or more of its arguments. This works well if some of the arguments are paging parameters.
+
+Learn more about the `@listSize` directive [here](/federation/federated-schemas/federated-directives/#listsize).
+
 ### Enforce cost limits
 
 After determining the cost estimation model of your operations, you should update and enforce the new cost limits.
@@ -440,6 +455,49 @@ Assuming each review having exactly one author, the total cost of the query is 2
 
 </ExpansionPanel>
 
+<MinVersion version="1.53.0">
+
+#### `@cost`
+
+</MinVersion>
+
+You can further customize the cost calculation with the `@cost` directive. This directive takes a `weight` argument which replaces the default weights outlined above.
+
+Revisiting the products query above, if the `topProducts.name` field is annotated with `@cost(weight: 5)`, then the total cost of the query increases to 56.
+
+<ExpansionPanel title="An example annotated Products schema">
+
+```graphql
+type Query {
+  topProducts: [Product]
+}
+
+type Product {
+  name: String! @cost(weight: 5)
+  reviews: [Review]
+}
+
+type Review {
+  author: Author!
+}
+
+type Author {
+  name: String!
+}
+```
+
+</ExpansionPanel>
+
+<ExpansionPanel title="Example query's updated cost calculation">
+
+```text disableCopy=true showLineNumbers=false
+1 Query (0 cost) + 6 product objects (6) + 6 name scalars (30) + 10 review objects (10) + 10 author objects (10) + 10 name scalars (0) = 56 total cost
+```
+
+</ExpansionPanel>
+
+Learn more about the `@cost` directive [here](/federation/federated-schemas/federated-directives/#cost).
+
 ### Estimated and actual costs
 
 For an operation with list fields, the router must run the operation to get the actual number of items in its lists. Without actual list sizes, the cost of an operation can only be estimated before it's executed, where you assume the size of lists.