Define your model types
@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: ModelQueryMap3 mutations: ModelMutationMap4 subscriptions: ModelSubscriptionMap5 timestamps: TimestampConfiguration6) on OBJECT7input ModelMutationMap {8 create: String9 update: String10 delete: String11}12input ModelQueryMap {13 get: String14 list: String15}16input ModelSubscriptionMap {17 onCreate: [String]18 onUpdate: [String]19 onDelete: [String]20 level: ModelSubscriptionLevel21}22enum ModelSubscriptionLevel {23 off24 public25 on26}27input TimestampConfiguration {28 createdAt: String29 updatedAt: String30}
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 Post2 @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 Post2 @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
, andsubscriptions
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: String4 metadata: MetaData5}6type MetaData {7 category: Category8}9enum Category {10 comedy11 news12}
would generate the following schema parts
1type Post {2 id: ID!3 title: String!4 metadata: MetaData5 createdAt: AWSDatetime6 updatedAt: AWSDateTime7}8
9type MetaData {10 category: Category11}12
13enum Category {14 comedy15 news16}17
18input MetaDataInput {19 category: Category20}21
22enum ModelSortDirection {23 ASC24 DESC25}26
27type ModelPostConnection {28 items: [Post]29 nextToken: String30}31
32input ModelStringFilterInput {33 ne: String34 eq: String35 le: String36 lt: String37 ge: String38 gt: String39 contains: String40 notContains: String41 between: [String]42 beginsWith: String43}44
45input ModelIDFilterInput {46 ne: ID47 eq: ID48 le: ID49 lt: ID50 ge: ID51 gt: ID52 contains: ID53 notContains: ID54 between: [ID]55 beginsWith: ID56}57
58input ModelIntFilterInput {59 ne: Int60 eq: Int61 le: Int62 lt: Int63 ge: Int64 gt: Int65 contains: Int66 notContains: Int67 between: [Int]68}69
70input ModelFloatFilterInput {71 ne: Float72 eq: Float73 le: Float74 lt: Float75 ge: Float76 gt: Float77 contains: Float78 notContains: Float79 between: [Float]80}81
82input ModelBooleanFilterInput {83 ne: Boolean84 eq: Boolean85}86
87input ModelPostFilterInput {88 id: ModelIDFilterInput89 title: ModelStringFilterInput90 and: [ModelPostFilterInput]91 or: [ModelPostFilterInput]92 not: ModelPostFilterInput93}94
95type Query {96 getPost(id: ID!): Post97 listPosts(98 filter: ModelPostFilterInput99 limit: Int100 nextToken: String101 ): ModelPostConnection102}103
104input CreatePostInput {105 title: String!106 metadata: MetaDataInput107}108
109input UpdatePostInput {110 id: ID!111 title: String112 metadata: MetaDataInput113}114
115input DeletePostInput {116 id: ID117}118
119type Mutation {120 createPost(input: CreatePostInput!): Post121 updatePost(input: UpdatePostInput!): Post122 deletePost(input: DeletePostInput!): Post123}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}