Read application data

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.

type Todo @model @auth(rules: [{ allow: owner }]) {
  content: String
}

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.

type Todo
  @model
  @auth(rules: [{ allow: public, operations: [read] }, { allow: owner }]) {
  content: String
}

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.

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:

import { generateClient } from 'aws-amplify/api';
import * as queries from './graphql/queries';

const client = generateClient();

const todos = await client.graphql({
  query: queries.listTodos,
  authMode: GRAPHQL_AUTH_MODE.AWS_IAM
});

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:

listTodos(
  filter: ModelTodoFilterInput
  limit: Int
  nextToken: String): ModelTodoConnection

input ModelTodoFilterInput {
	id: ModelIDInput
	priority: ModelIntInput
	# ... all your other Todo fields here
	and: [ModelTodoFilterInput]
	or: [ModelTodoFilterInput]
	not: ModelTodoFilterInput
}

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:

input ModelIntInput {
  ne: Int # "not equal to"
  eq: Int # "equal to"
  le: Int # "less than or equal to"
  lt: Int # "less than"
  ge: Int # "greater than or equal to"
  gt: Int # "greater than"
  between: [Int]
  attributeExists: Boolean
  attributeType: ModelAttributeTypes
}

These filters vary based on the type of the field, but are linked to corresponding Amazon DynamoDB queries.

This brief walkthrough provides additional step-by-step guidance for implementing pagination.

When working with a large record set, you may want to only fetch the first N number of items. For example, let's start with a basic GraphQL schema for a Todo app:

type Todo @model {
  id: ID!
  title: String!
  description: String
}

When the API is created with an @model directive, the following queries will automatically be created for you:

type Query {
  getTodo(id: ID!): Todo
  listTodos(
    filter: ModelTodoFilterInput
    limit: Int
    nextToken: String
  ): ModelTodoConnection
}

Next, take a look at the ModelTodoConnection type to get an idea of the data that will be returned when the listTodos query is run:

type ModelTodoConnection {
  items: [Todo]
  nextToken: String
}

When querying the API using the listTodos query, the return type will be of ModelTodoConnection, meaning you can return both an array of Todos and a nextToken.

The nextToken handles pagination. If the nextToken is null, that means there is no more data to return from the API. If the nextToken is present, you can use the value as an argument to the next listTodos query to return the next selection set from the API.

To test this, try creating five Todos using a mutation like this:

mutation createTodo {
  createTodo(input: {
    title: "Todo 1"
    description: "My first todo"
  }) {
    id
    title
    description
  }
}

Next, you can set the limit of the number of Todos in a query by specifying a limit argument. In this query, you will set the limit to two items and request a nextToken as a return value:

query listTodos {
  listTodos(limit: 2) {
    items {
      id
      title
      description
    }
    nextToken
  }
}

Now, to query the next two items from the API, specify this nextToken as the argument:

query listTodos {
  listTodos(limit: 2, nextToken: <your_token>) {
    items {
      id
      title
      description
    }
    nextToken
  }
}

When there are no other items left to be returned, the nextToken in the response will be set to null.

Querying from a JavaScript application

The listTodos query is auto-generated by the CLI; for reference, it should look something like this:

const listTodos = `
  query listTodos($limit: Int) {
    listTodos(limit: $limit) {
      items {
        id
        title
        description
      }
      nextToken
    }
  }
`;

To specify a limit in a query from a JavaScript application, you can use the following code by setting the limit as a variable:

import { generateClient } from 'aws-amplify/api';

const client = generateClient();

async function fetchTodos() {
  const todoData = await client.graphql({
    query: listTodos,
    variables: {
      limit: 2
    }
  });
  console.log({ todoData });
}

The data returned from the API request should look like this (with the items array containing however many items have been created):

{
  "data" {
    "listTodos" {
      "items": [{ id: "001", title: "Todo 1", description: "My first todo" }],
      "nextToken": "<token-id>"
    }
  }
}

To set the nextToken in a query from a JavaScript application, you can use the following code:

import { generateClient } from 'aws-amplify/api';

const client = generateClient();

async function fetchTodos() {
  const todoData = await client.graphql({
    query: listTodos,
    variables: {
      limit: 2,
      nextToken: '<token-id>'
    }
  });
  console.log({ todoData });
}