Document how the front end is expected to query 'createdBy'

[mgreiner79]

Environment information

System:
  OS: macOS 26.1
  CPU: (8) arm64 Apple M1
  Memory: 186.34 MB / 8.00 GB
  Shell: /bin/zsh
Binaries:
  Node: 20.19.6 - <REDACTED>/.nvm/versions/node/v20.19.6/bin/node
  Yarn: undefined - undefined
  npm: 10.8.2 - <REDACTED>/.nvm/versions/node/v20.19.6/bin/npm
  pnpm: undefined - undefined
NPM Packages:
  @aws-amplify/auth-construct: 1.9.0
  @aws-amplify/backend: 1.18.0
  @aws-amplify/backend-ai: Not Found
  @aws-amplify/backend-auth: 1.8.0
  @aws-amplify/backend-cli: 1.8.0
  @aws-amplify/backend-data: 1.6.2
  @aws-amplify/backend-deployer: 2.1.4
  @aws-amplify/backend-function: 1.15.1
  @aws-amplify/backend-output-schemas: 1.7.1
  @aws-amplify/backend-output-storage: 1.3.2
  @aws-amplify/backend-secret: 1.4.1
  @aws-amplify/backend-storage: 1.4.2
  @aws-amplify/cli-core: 2.2.2
  @aws-amplify/client-config: 1.9.0
  @aws-amplify/data-construct: 1.16.3
  @aws-amplify/data-schema: 1.22.0
  @aws-amplify/deployed-backend-client: 1.8.1
  @aws-amplify/form-generator: 1.2.5
  @aws-amplify/model-generator: 1.2.1
  @aws-amplify/platform-core: 1.10.2
  @aws-amplify/plugin-types: 1.11.1
  @aws-amplify/sandbox: 2.1.3
  @aws-amplify/schema-generator: 1.4.1
  @aws-cdk/toolkit-lib: 1.6.1
  aws-amplify: 6.15.8
  aws-cdk-lib: 2.225.0
  typescript: 5.9.3
No AWS environment variables
No CDK environment variables

Describe the feature

There should be documentation explaining the intended way to filter items by the user who created them.

Use case

How is the front-end supposed to filter by items created by the current user?

From what I understand, the backend auto generates owner. In data/resource.ts we can give an alias to owner and call it, for example createdBy, by doing this

.authorization((allow) => [
      allow.ownerDefinedIn('createdBy').to(['create', 'read', 'update', 'delete']),
    ]),

In this case, amplify will auto-fill the createdBy field.

But on the front-end, in order to query by that field to get just the items that the current user created, I need to do

 const resp = await client.models.Space.list({
            filter: {
                createdBy: { eq: `${userSub}::${userSub}` },
            },
        });

This :: structure, is it stable? is it recommended to filter like this?

Note, the user will get all of their created items if you provide no filter at all. But if you have a model with auth like this

.authorization((allow) => [
      allow.ownerDefinedIn('createdBy').to(['create', 'read', 'update', 'delete']),
allow.authenticated().to(['read'])
    ]),

Then, without the filter, you will get everything; not just the ones the user created.

Also, I don't think it is a good pattern to use a custom createdBy field and populate it on the front end. This means on the front end you always need to consider whether you will ever want to query this model by the user who created it, and if so, then pass some reliable user identifier to the api layer on creation. And you need to do this for every model where this is the case.

It would be best if the backend always stored the creator identity (like it does for time created and time updated), and provides a reliable way for the front end to query it.

TLDR

Is it really expected to query for items created by user using this pattern?

 const resp = await client.models.Space.list({
            filter: {
                createdBy: { eq: `${userSub}::${userSub}` },
            },
        });

and if so, can this be documented somewhere, with details explaining this :: structure? Is it always ::, or does it fallback to that pattern, for example, if some other field is not present?

[pahud]

Hi @mgreiner79,

Thank you for bringing this up.

The ${userSub}::${userSub} pattern you discovered is indeed the correct and stable approach for filtering by owner fields. This format is part of AWS AppSync's owner authorization implementation. The double-colon delimiter separates the Cognito sub (user ID) from the username claim.

Why This Format Exists

The owner field format is {cognito:sub}::{cognito:username} by default. You can see this referenced in the Authorization.ts source code where it mentions "in place of sub::username".

https://github.com/aws-amplify/amplify-data/blob/c5d4e1dc4c8f1740ce88303977191e880f99f043/packages/data-schema/src/Authorization.ts#L159-L173

When Filtering Is Needed

Your observation about needing to filter is correct. Here's why:

Scenario A - Owner-only auth (automatic filtering):

.authorization((allow) => [
  allow.ownerDefinedIn('createdBy').to(['create', 'read', 'update', 'delete'])
])

Backend automatically filters - you only get your items.

Scenario B - Mixed auth (manual filtering required):

.authorization((allow) => [
  allow.ownerDefinedIn('createdBy').to(['create', 'read', 'update', 'delete']),
  allow.authenticated().to(['read'])
])

Backend returns all items (because authenticated users can read everything). You need to filter on the frontend:

const resp = await client.models.Space.list({
  filter: {
    createdBy: { eq: `${userSub}::${userSub}` }
  }
});

Documentation Enhancement

I agree this should be documented. This appears to be a documentation gap rather than a product issue. The behavior is working as designed, but the owner field format and filtering patterns aren't clearly explained in the user-facing documentation.