Define your model types

You are currently viewing the legacy GraphQL Transformer documentation. View latest documentation

@model

Object types that are annotated with @model are top-level entities in the generated API. Objects annotated with @model are stored in Amazon DynamoDB and are capable of being protected via @auth, related to other objects via @connection, and streamed into Amazon OpenSearch via @searchable. You may also apply the @versioned directive to instantly add a version field and conflict detection to a model type.

Definition

The following SDL defines the @model directive that allows you to easily define top level object types in your API that are backed by Amazon DynamoDB.

1directive @model(
2 queries: ModelQueryMap
3 mutations: ModelMutationMap
4 subscriptions: ModelSubscriptionMap
5 timestamps: TimestampConfiguration
6) on OBJECT
7input ModelMutationMap {
8 create: String
9 update: String
10 delete: String
11}
12input ModelQueryMap {
13 get: String
14 list: String
15}
16input ModelSubscriptionMap {
17 onCreate: [String]
18 onUpdate: [String]
19 onDelete: [String]
20 level: ModelSubscriptionLevel
21}
22enum ModelSubscriptionLevel {
23 off
24 public
25 on
26}
27input TimestampConfiguration {
28 createdAt: String
29 updatedAt: String
30}

Usage

Define a GraphQL object type and annotate it with the @model directive to store objects of that type in DynamoDB and automatically configure CRUDL queries and mutations.

1type Post @model {
2 id: ID! # id: ID! is a required attribute.
3 title: String!
4 tags: [String!]!
5}

You may also override the names of any generated queries, mutations and subscriptions, or remove operations entirely.

1type Post
2 @model(queries: { get: "post" }, mutations: null, subscriptions: null) {
3 id: ID!
4 title: String!
5 tags: [String!]!
6}

This would create and configure a single query field post(id: ID!): Post and no mutation fields.

Model directive automatically adds createdAt and updatedAt timestamps to each entities. The timestamp field names can be changed by passing timestamps attribute to the directive

1type Post
2 @model(timestamps: { createdAt: "createdOn", updatedAt: "updatedOn" }) {
3 id: ID!
4 title: String!
5 tags: [String!]!
6}

The above schema will generate Post with createdOn and updatedOn fields as shown

1type Post {
2 id: ID!
3 title: String!
4 tags: [String!]!
5 createdOn: AWSDateTime!
6 updatedOn: AWSDateTime!
7}

The automatically added createdAt and updatedAt fields can't be set in create or update mutation. If these fields need to be controlled as part of the mutation, they should be in the input schema and should have AWSDateTime as their type

1type Post @model {
2 id: ID!
3 title: String!
4 tags: [String!]!
5 createdAt: AWSDateTime!
6 updatedAt: AWSDateTime!
7}

Generates

A single @model directive configures the following AWS resources:

  • An Amazon DynamoDB table with PAY_PER_REQUEST billing mode enabled by default.
  • An AWS AppSync DataSource configured to access the table above.
  • An AWS IAM role attached to the DataSource that allows AWS AppSync to call the above table on your behalf.
  • Up to 8 resolvers (create, update, delete, get, list, onCreate, onUpdate, onDelete) but this is configurable via the queries, mutations, and subscriptions arguments on the @model directive.
  • Input objects for create, update, and delete mutations.
  • Filter input objects that allow you to filter objects in list queries and connection fields.
  • For list queries the default number of objects returned is 100. You can override this behavior by setting the limit argument.

This input schema document

1type Post @model {
2 id: ID!
3 title: String
4 metadata: MetaData
5}
6type MetaData {
7 category: Category
8}
9enum Category {
10 comedy
11 news
12}

would generate the following schema parts

1type Post {
2 id: ID!
3 title: String!
4 metadata: MetaData
5 createdAt: AWSDatetime
6 updatedAt: AWSDateTime
7}
8
9type MetaData {
10 category: Category
11}
12
13enum Category {
14 comedy
15 news
16}
17
18input MetaDataInput {
19 category: Category
20}
21
22enum ModelSortDirection {
23 ASC
24 DESC
25}
26
27type ModelPostConnection {
28 items: [Post]
29 nextToken: String
30}
31
32input ModelStringFilterInput {
33 ne: String
34 eq: String
35 le: String
36 lt: String
37 ge: String
38 gt: String
39 contains: String
40 notContains: String
41 between: [String]
42 beginsWith: String
43}
44
45input ModelIDFilterInput {
46 ne: ID
47 eq: ID
48 le: ID
49 lt: ID
50 ge: ID
51 gt: ID
52 contains: ID
53 notContains: ID
54 between: [ID]
55 beginsWith: ID
56}
57
58input ModelIntFilterInput {
59 ne: Int
60 eq: Int
61 le: Int
62 lt: Int
63 ge: Int
64 gt: Int
65 contains: Int
66 notContains: Int
67 between: [Int]
68}
69
70input ModelFloatFilterInput {
71 ne: Float
72 eq: Float
73 le: Float
74 lt: Float
75 ge: Float
76 gt: Float
77 contains: Float
78 notContains: Float
79 between: [Float]
80}
81
82input ModelBooleanFilterInput {
83 ne: Boolean
84 eq: Boolean
85}
86
87input ModelPostFilterInput {
88 id: ModelIDFilterInput
89 title: ModelStringFilterInput
90 and: [ModelPostFilterInput]
91 or: [ModelPostFilterInput]
92 not: ModelPostFilterInput
93}
94
95type Query {
96 getPost(id: ID!): Post
97 listPosts(
98 filter: ModelPostFilterInput
99 limit: Int
100 nextToken: String
101 ): ModelPostConnection
102}
103
104input CreatePostInput {
105 title: String!
106 metadata: MetaDataInput
107}
108
109input UpdatePostInput {
110 id: ID!
111 title: String
112 metadata: MetaDataInput
113}
114
115input DeletePostInput {
116 id: ID
117}
118
119type Mutation {
120 createPost(input: CreatePostInput!): Post
121 updatePost(input: UpdatePostInput!): Post
122 deletePost(input: DeletePostInput!): Post
123}
124
125type Subscription {
126 onCreatePost: Post @aws_subscribe(mutations: ["createPost"])
127 onUpdatePost: Post @aws_subscribe(mutations: ["updatePost"])
128 onDeletePost: Post @aws_subscribe(mutations: ["deletePost"])
129}