You can read application data using the Amplify GraphQL client. In this guide, we will review the difference between reading data and getting data, how to filter query results to get just the data you need, and how to paginate results to make your data more manageable. We will also show you how to cancel these requests when needed.
Before you begin, you will need:
Queries are used to read data through the API and include the list and get operations.
The Amplify CLI automatically creates list and get queries for any @model type in your GraphQL API. The list query retrieves multiple items, such as Todo items, without needing to specific an identifier for a particular record. This is best suited for getting an overview or summary of items, or for enhancing the list operation to filter the items by specific criteria. When you want to query a single entry by an identifier, you would use get to retrieve a specific Todo item.
Note: The cost structure of your underlying data source can impact the cost to run some queries. For example, the list operation uses Amazon DynamoDB "scan operations," which can use more read request units than the get operation. You will want to review the associated costs for these operations for your data source. In our example, we are using DynamoDB. You can learn more about how DynamoDB costs are calculated by visiting Amazon DynamoDB pricing.
The Amplify CLI automatically generates GraphQL client code for all possible GraphQL operationsâmutations, queries, and subscriptions. For JavaScript applications, this generated code is saved in the src/graphql folder by default.
To run a GraphQL query, import the generated query and run it with client.graphql:
Troubleshooting
Troubleshoot unauthorized errors
You can run into unauthorized errors if you don't have at least one auth rule defined.
Use the @auth directive to configure authorization rules for public, signed-in user, per-user, and per-user-group data access. Authorization rules operate on the deny-by-default principle, meaning that if an authorization rule is not specifically configured, it is denied.
In the previous example, each signed-in user, or "owner", of a Todo can create, read, update, and delete their own Todos.
Amplify also allows you to restrict the allowed operations, combine multiple authorization rules, and apply fine-grained field-level authorization.
In the previous example, everyone (public) can read every Todo, but the owner (authenticated users) can create, read, update, and delete their own Todos.
To learn more, see Authorization rules for the GraphQL API.
Learn more
Custom authorization mode to query data
Each AWS AppSync API uses a default authorization mode when you configure your app. To override this default, pass an authMode property. For example, this is useful when you have public reads through API Key auth and authenticated reads through IAM auth. The following examples show how you can query data with the custom authorization mode:
As your data grows, you will need to paginate your list queries. Fortunately, this is already built in to the Amplify-generated GraphQL API.
Learn more
How do filters work?
You can find the input schemas in the Docs pane of the GraphQL explorer or inside your auto-generated /graphql folder. They look like this:
The input types in your schema indicate what kinds of filtering you can perform on them. For example, an integer field like ModelIntInput has this schema:
These filters vary based on the type of the field, but are linked to corresponding Amazon DynamoDB queries.
Compound filtersYou can combine filters with and, or, and not Boolean logic. Observe, in the previous auto-generated schema, that ModelTodoFilterInput is recursive in respect to those fields. So if, for example, you wanted to filter for priority values of 1 or 2, you would do this:
Note that querying for priority of 1 and 2 would return no results, because this is Boolean logic instead of natural language.
To paginate your list query results, make a subsequent list query request with the nextToken and limit input variable set. The limit variable limits how many results are returned. The response will include a nextToken you can use to request the next page of data. A nextToken is a very long string that represents the cursor to the starting item of the next query made with these filters.
You may cancel any query or mutation request made through the API category by keeping a reference to the promise returned.
You need to ensure that the promise returned from client.graphql() has not been modified. Typically, async functions wrap the promise being returned into another promise. For example, the following will not work:
Congratulations! You have finished the Read application data guide. In this guide, you learned how to read your data through get and list queries.
Our recommended next steps include subscribing to real-time events to look for mutations in your data and continuing to build out and customize your information architecture for your data. Some resources that will help with this work include:
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4