diff --git a/src/pages/gen2/build-a-backend/data/data-modeling/secondary-index/index.mdx b/src/pages/gen2/build-a-backend/data/data-modeling/secondary-index/index.mdx index dfae85a43c4..b37f89c14e8 100644 --- a/src/pages/gen2/build-a-backend/data/data-modeling/secondary-index/index.mdx +++ b/src/pages/gen2/build-a-backend/data/data-modeling/secondary-index/index.mdx @@ -14,44 +14,41 @@ export function getStaticProps(context) { You can optimize your list queries based on "secondary indexes". For example, if you have a **Customer** model, you can query based on the customer's **id** identifier field by default but you can add a secondary index based on the **accountRepresentativeId** to get list customers for a given account representative. -A secondary index consists of a "hash key" and, optionally, a "sort key". Use the "hash key" to perform strict equality and the "sort key" for greater than (gt), greater than or equal to (ge), less than (lt), less than or equal to (le), equals (eq), begins with, and between operations. +A secondary index consists of a "hash key" and, optionally, a "sort key". Use the "hash key" to perform strict equality and the "sort key" for greater than (gt), greater than or equal to (ge), less than (lt), less than or equal to (le), equals (eq), begins with, and between operations. -```ts +```ts title="amplify/data/resource.ts" export const schema = a.schema({ - Customer: a.model({ - name: a.string(), - phoneNumber: a.phone(), - accountRepresentativeId: a.id().required() - // highlight-start - }).secondaryIndexes(index => [ - index('accountRepresentativeId') - ]) - // highlight-end - .authorization([a.allow.public()]), + Customer: a + .model({ + name: a.string(), + phoneNumber: a.phone(), + accountRepresentativeId: a.id().required(), + }) + // highlight-next-line + .secondaryIndexes((index) => [index("accountRepresentativeId")]) + .authorization([a.allow.public()]), }); ``` The example client query below allows you to query for "Customer" records based on their `accountRepresentativeId`: -```ts +```ts title="src/App.tsx" import { type Schema } from '../amplify/data/resource'; import { generateClient } from 'aws-amplify/data'; const client = generateClient(); -const { - data, - errors +const { data, errors } = // highlight-start -} = await client.models.Customer.listByAccountRepresentativeId({ - accountRepresentativeId: "YOUR_REP_ID" -}); - // highlight-end + await client.models.Customer.listByAccountRepresentativeId({ + accountRepresentativeId: "YOUR_REP_ID", + }); +// highlight-end ``` -Amplify uses Amazon DynamoDB tables as the default data source for `a.model()`. For key-value databases, it is critical to model your access patterns with "secondary indexes". Use the `.index()` modifier to configure a secondary index. +Amplify uses Amazon DynamoDB tables as the default data source for `a.model()`. For key-value databases, it is critical to model your access patterns with "secondary indexes". Use the `.index()` modifier to configure a secondary index. **Amazon DynamoDB** is a key-value and document database that delivers single-digit millisecond performance at any scale but making it work for your access patterns requires a bit of forethought. DynamoDB query operations may use at most two attributes to efficiently query data. The first query argument passed to a query (the hash key) must use strict equality and the second attribute (the sort key) may use gt, ge, lt, le, eq, beginsWith, and between. DynamoDB can effectively implement a wide variety of access patterns that are powerful enough for the majority of applications. @@ -59,35 +56,39 @@ Amplify uses Amazon DynamoDB tables as the default data source for `a.model()`. ## Add sort keys to secondary indexes -You can define "sort keys" to add a set of flexible filters to your query, such as "greater than" (gt), "greater than or equal to" (ge), "less than" (lt), "less than or equal to" (le), "equals" (eq), "begins with" (beginsWith), and "between" operations. +You can define "sort keys" to add a set of flexible filters to your query, such as "greater than" (gt), "greater than or equal to" (ge), "less than" (lt), "less than or equal to" (le), "equals" (eq), "begins with" (beginsWith), and "between" operations. ```ts title="amplify/data/resource.ts" -const schema = a.schema({ - Customer: a.model({ - name: a.string(), - phoneNumber: a.phone().required(), - accountRepresentativeId: a.id().required(), - }).secondaryIndexes(index => [ - index('accountRepresentativeId') - // highlight-next-line - .sortKeys(["name"]), - ]) -}).authorization([a.allow.owner()]); +export const schema = a.schema({ + Customer: a + .model({ + name: a.string(), + phoneNumber: a.phone(), + accountRepresentativeId: a.id().required(), + }) + .secondaryIndexes((index) => [ + index("accountRepresentativeId") + // highlight-next-line + .sortKeys(["name"]), + ]) + .authorization([a.allow.owner()]), +}); ``` On the client side, you should find a new `listBy...` query that's named after hash key and sort keys. For example, in this case: `listByAccountRepresentativeIdAndName`. You can supply the filter as part of this new list query: -```ts +```ts title="src/App.tsx" const { data, errors - // highlight-next-line -} = await client.models.Customer.listByAccountRepresentativeIdAndName({ - accountRepresentativeId: 'YOUR_REP_ID', - name: { - beginsWith: 'Rene', - }, -}); +} = +// highlight-next-line + await client.models.Customer.listByAccountRepresentativeIdAndName({ + accountRepresentativeId: 'YOUR_REP_ID', + name: { + beginsWith: 'Rene', + }, + }); ``` ## Customize the query field for secondary indexes @@ -96,21 +97,24 @@ You can also customize the auto-generated query name under `client.models. [ - index('accountRepresentativeId') - // highlight-next-line - .queryField("listByRep"), - ]), -}).authorization([a.allow.owner()]); + Customer: a + .model({ + name: a.string(), + phoneNumber: a.phone(), + accountRepresentativeId: a.id().required(), + }) + .secondaryIndexes((index) => [ + index("accountRepresentativeId") + // highlight-next-line + .queryField("listByRep"), + ]) + .authorization([a.allow.owner()]), +}); ``` In your client app code, you'll see query updated under the Data client: -```ts +```ts title="src/App.tsx" const { data, errors @@ -124,16 +128,19 @@ const { To customize the underlying DynamoDB's index name, you can optionally provide the `name()` modifier. -```ts +```ts title="amplify/data/resource.ts" const schema = a.schema({ - Customer: a.model({ - name: a.string(), - phoneNumber: a.phone(), - accountRepresentativeId: a.id().required(), - }).secondaryIndexes(index => [ - index('accountRepresentativeId') - // highlight-next-line - .name("MyCustomIndexName"), - ]) -}).authorization([a.allow.owner()]); + Customer: a + .model({ + name: a.string(), + phoneNumber: a.phone(), + accountRepresentativeId: a.id().required(), + }) + .secondaryIndexes((index) => [ + index("accountRepresentativeId") + // highlight-next-line + .name("MyCustomIndexName"), + ]) + .authorization([a.allow.owner()]), +}); ```