Relations

Define queryable relationships between models and other models or accounts.

Types of Relations

There are a few primary forms of relations currently supported by ComposeDB:

• Account to model
• Model to account
• Model to model
• Account to account

Account to Model

Account to model relations enable linking and querying data to the account that created it. By default the @createmodel directive (used when creating a new model) requires that every model must specify a relation to its author’s account. This was covered in Writing Models.

Example: Simple Profile

Here’s a model for a very simple user profile that can be queried based on the author:

# Define simple profile model
# Relate it to the author's account
# Limit to one profile per account
# Enable queries based on author

type SimpleProfile @createModel(accountRelation: SINGLE, description: "Very basic profile") {
  displayName: String! @string(minLength: 3, maxLength: 50)
}

Where:

• accountRelation relates the profile to the author’s account
• SINGLE limits to one profile per account

Model to Account

Model to account relations enable you to link data to and query data from an account other than the data’s author. When using this type of relation, you need to define a model field that stores an account (e.g. a DID), then add the @accountReference directive to make it queryable.

Example: Direct message (DM)

Here’s a model for a user-to-user message that can be queried based on the recipient:

# Define message model
# Relate it to author's account
# Allow unlimited sent messages
# Store reference to recipient's account
# Enable queries based on recipient

type Message @createModel(accountRelation: LIST, description: "Direct message model") {
  recipient: DID! @accountReference
    directMessage: String! @string(minLength: 1, maxLength: 200)
}

Where:

• accountRelation relates the message to the author’s account
• LIST allows unlimited messages
• recipient references the recipient’s account by storing its DID!, using @accountReference

Model to Model

Model to model relations enable you to link data to and query data from another piece of data. These relations can be uni-directional (e.g. query a post from a comment) or bi-directional (e.g. query a post from a comment and query all comments from a post).

Example: Post with comments

Here’s a model that allows many comments to be made on a single post. It supports unlimited comments per user, and bi-directional queries from any comment to the original post and from the original post to all of its comments.

# Load post model (using streamID)

type Post @loadModel(id: "kjzl6hvfrbw6c99mdfpjx1z3fue7sesgua6gsl1vu97229lq56344zu9bawnf96"){
    id: ID!
}

# New comment model
# Set relationship to original post
# Enable querying comment to get original post

type Comment @createModel(accountRelation: LIST, description: "A comment on a Post") {
  postID: StreamID! @documentReference(model: "Post")
  post: Post! @relationDocument(property: "postID")
  text: String! @string(maxLength: 500)
}

Relations can also be created between models loaded from known streamIDs

# Load comment model

type Comment @loadModel(id: "kjzl6hvfrbw6c9oo2ync09y6z5c9mas9u49lfzcowepuzxmcn3pzztvzd0c7gh0") {
  id: ID!
}

# Load post model
# Extend post model with comments
# Set relationships to all comments
# Enable querying post to get all comments

type Post @loadModel(id: "kjzl6hvfrbw6c99mdfpjx1z3fue7sesgua6gsl1vu97229lq56344zu9bawnf96") {
  comments: [Comment] @relationFrom(model: "Comment", property: "postID")
}

Where:

• id is a simple placeholder, since empty types are not allowed
• postID defines the relationship from a comment to the original post, using @documentReference
• post allows accessing the original post from the comment, using @relationDocument
• text defines a string for the comment
• comments defines the relationships from a post to a collection of comments, using @relationFrom; requires specifying the model relation (Comment) and the specific property that stores the relation (postID)

Example: Container with Items

Please see Relations: Container of Items

Account to Account

caution

Account to account relations are on the roadmap, but not yet supported.

Account to account relations enable you to define a relationship between an account and a different account, and query both ways based on that relationship. This is useful for creating structures such as social graphs where the relationship represents a follow.

Next Steps

Now that you understand the fundamentals of creating models with different types of relations, learn how to create composites using them.

Head to Composites next to learn more →