fix: CPK uni-directional has-many lazy list load

[lawmicha]

Issue #

Table of contents

• Library Changes data-dev-preview fix: CPK uni-directional has-many lazy list load #2730 (You are here)
• Library Changes v1 - fix(v1): CPK has-many has-one associatedFields #2734
• Library Changes main - fix: CPK has-many has-one associatedFields #2735
• Codegen Changes - fix(amplify-codegen): swift - add has-many associatedFields for CPK use case amplify-codegen#538

Description

This PR fixes the use case for lazy loading a list for uni-directional has-many use cases where the parent model contains a custom primary key. A uni-directional has-many use case is the following:

# LL.7. Implicit Uni-directional Has Many
# CLI.4. Implicit Uni-directional Has Many

type Post4 @model {
  postId: ID! @primaryKey(sortKeyFields:["title"])
  title: String!
  comments: [Comment4] @hasMany
}
type Comment4 @model {
  commentId: ID! @primaryKey(sortKeyFields:["content"])
  content: String!
}

# LL.11. Explicit Uni-directional Has Many
# CLI.8. Explicit Uni-directional Has Many

type Post8 @model {
  postId: ID! @primaryKey(sortKeyFields:["title"])
  title: String!
  comments: [Comment8] @hasMany(indexName:"byPost", fields:["postId", "title"])
}
type Comment8 @model {
  commentId: ID! @primaryKey(sortKeyFields:["content"])
  content: String!
  postId: ID @index(name: "byPost", sortKeyFields:["postTitle"]) # customized foreign key for parent primary key
  postTitle: String # customized foreign key for parent sort key
}

The Post has a custom primary key (postId and title), and the child does not have a model reference to the post.

Querying for a post, and then traversing to the comment, and lazy loading the comment previously was incorrectly constructing the filter (Query for Comments by filter on post identifiers). It was missing the post's second identifier of the composite key.

LazyList's query for comments by postId == post.id

The correct logic is to do

LazyList's query for comments by postId == post.id && postTitle == post.title

This is working for bi-directional since the post reference on the comment can resolve the targetNames (fields on the Comment, which reference the post). It is not working on for uni-directional because the Comment does not have a reference to the post, only the fields of the post's composite key on the comment.

This PR manually modifies the codegenerated types to include the associatedFieldNames on the comments field on the Post. When querying for a post, the associatedFieldNames will be used if available to pass which fields to construct the filter on. This is only necessary when the parent model has a composite primary key. The changes in this PR is backwards compatible with previous codegenerated hasMany relationships which do not contain associatedFieldNames, however the use case can only be solved for the customer when they upgrade to the latest codegen and regenerate the models with the associatedFieldNames.

Examples use cases

Use case: bi-directional has-many belongs-to

Comment belongs-to Post will have a reference like "post"

struct Comment: Model {
  var post: Post
}

associatedFields will be ["post"].
associatedIdentifiers will be ["postId123"]

query(Comment.self, filter: field("post") == associatedIdentifiers[0])

Use case: bi-directional has-many belongs-to with CPK on parent

struct Comment: Model {
  var post: Post
}
extension Comment {
   .belongsTo(comment.post, is: .optional, ofType: Post.self, targetNames: ["postId", "postTitle"]),
}
struct Post: Model {
  var id: //
  var title // title being a primary key of post
}

associatedFields will be ["post"].
associatedIdentifiers will be ["postId123", "title123"]

let columnNames = getColumnNames(["post"]) // ["postId", "postTitle"]
query(Comment.self, filter: field("postId") == "postId123" && field("postTitle") == "title123")

Use case: uni-directional has-many

struct Comment: Model {
  var postId: String
}

struct Post: Model {
  var id: String
}

associatedFields will be ["postId"].
associatedIdentifiers will be ["postId123"]

query(Comment.self, filter: field("postId") == "postId123")

Use case: uni-directional has-many with CPK on parent

This is the use case that has a problem being fixed by this PR (and codegen changes to add associatedFields to the hasMany modelField)

struct Comment: Model {
  var postId: String
  var postTitle: String
}


struct Post: Model {
  var id: String
  var title: String
  var comments: List<Comment>
}
extension Post {
  .hasMany(post.comments, is: .optional, ofType: Comment4.self, associatedFields: [Comment.keys.postId, Comment.keys.postTitle]),
}

associatedFields will be ["postId", "postTitle"].
associatedIdentifiers will be ["postId123", "title123"]

query(Comment.self, filter: field("postId") == "postId123" && field("postTitle") == "title123")

General Checklist

• Added new tests to cover change, if needed
• Build succeeds with all target using Swift Package Manager
• All unit tests pass
• All integration tests pass
• Security oriented best practices and standards are followed (e.g. using input sanitization, principle of least privilege, etc)
• Documentation update for the change if required
• PR title conforms to conventional commit style
• New or updated tests include Given When Then inline code documentation and are named accordingly testThing_condition_expectation()
• If breaking change, documentation/changelog update with migration instructions

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

[lawmicha]

Updated codegenerated schema files specify the targetNames, which are passed to the lazy list when instantiating it, thus a not loaded list will have the necessary field names of the post, that exist on the Comment, to query for the Comments by post identifiers.

[lawmicha]

this is the functional change to pass down the targetNames for lazy loading the uni-directional has-many use case. We have to extract out the values of the primary key values from the parent model, instead of just using the @@primaryKey field value.

[5d]

doesn't the targetNames only indicate the foreignKey composite key?

[lawmicha]

Yes I believe so, when the targetNames is on the hasMany modelField, they are the foreign keys fields of the parent model on the child model, which is an array due the parent model containing a composite key. For example, on the Post schema, the Post has a has-many reference to the Comments

.hasMany(post4.comments, is: .optional, ofType: Comment4.self, associatedWith: Comment4.keys.post4CommentsPostId, targetNames: ["post4CommentsPostId", "post4CommentsTitle"]),

The targetNames represent the "associated with fields". On the Comment model,

struct Comment {
  var post4CommentsPostId: String
  var post4CommentsTitle: String
}

Since the comment does not have a reference object to Post, there is no "post: Post" field on Comment, and the foreign key composite keys are just strings. The proposed change is to add "targetNames" to the parent model's hasMany fields to point to "post4CommentsPostId" and "post4CommentsTitle"

[lawmicha]

Since the Post8+schema.swift codegenerated file has been updated to include targetNames, they are used and passed as "postId" and "postTitle", which are the fields on the Comment8 to build the filter on, when lazy loading

[lawmicha]

This is the API functional change to pass the "targetNames" array or the "associatedKey", see associatedFieldNames

[lawmicha]

this is the proposed codegen changes

[5d]

LGTM!