Join to a relationship field in an array

[Because789]

This is related to #8424, but I'm not sure if it's a bug, a feature request, or just my poor understanding. If you add these two collections to a blank template (Node: 20.17.0, pnpm: 9.11.0, payload: 3.2.2, next: 15.0.0), an InvalidFieldJoin error is thrown:

import type { CollectionConfig } from 'payload'

export const Stories: CollectionConfig = {
  slug: 'stories',
  fields: [
    {
      name: 'concept_connections_array',
      label: 'Connections to Concepts',
      type: 'array',
      fields: [
        {
          name: 'related_concept',
          label: 'Related Concept',
          type: 'relationship',
          relationTo: 'concepts',
        },
      ],
    },
  ],
}

import type { CollectionConfig } from 'payload'

export const Concepts: CollectionConfig = {
  slug: 'concepts',
  fields: [
    {
      name: 'concept_name',
      type: 'text',
    },
    {
      name: 'stories_connections',
      type: 'join',
      collection: 'stories',
      on: 'concept_connections_array.related_concept',
      label: 'Stories referring to this concept',
    },
  ],
}

The Next.js error is: Error: Invalid join field stories_connections. The config does not have a field 'concept_connections_array.related_concept' in collection 'stories'. This would suggest, that there is something wrong with the on reference, but I fail to see what that could be. And in the Terminal we get the error:

  52 |     if (!joinRelationship) {
> 53 |         throw new InvalidFieldJoin(join.field);
     | ^
  54 |     }
  55 |     if (Array.isArray(joinRelationship.relationTo)) {
  56 |         throw new APIError('Join fields cannot be used with polymorphic relationships.');

As @DanRibbens states in the issue above: "I tested the feature with a join field on a relationship in an array and it does work." Shouldn't the above case work according to this? It seems to me that it should, but then again, I've been wrong before.

In any case, as a feature request, it would really be great to have a "limitations" section in the join field docs and less confusing error messages for this situation.

[DanRibbens]

I'd expect your config to work. This might just be an issue of not handling snake case field names. I will have to test this theory when I get some time. You may want to experiment with camelcase to rule this out while you wait on me.

Let me know if you figure anything out.

[Because789]

I updated my test environment to the latest dependencies (payload: 3.4.0, next: 15.0.3, react: 19.0.0-rc-66855b96-20241106) and tested with camel case:

import type { CollectionConfig } from 'payload'

export const Stories: CollectionConfig = {
  slug: 'stories',
  fields: [
    {
      name: 'conceptsArray',
      label: 'Connections to Concepts',
      type: 'array',
      fields: [
        {
          name: 'relatedConcept',
          label: 'Related Concept',
          type: 'relationship',
          relationTo: 'concepts',
        },
      ],
    },
  ],
}

import type { CollectionConfig } from 'payload'

export const Concepts: CollectionConfig = {
  slug: 'concepts',
  fields: [
    {
      name: 'conceptName',
      type: 'text',
    },
    {
      name: 'storiesConnections',
      type: 'join',
      collection: 'stories',
      on: 'conceptsArray.relatedConcept',
      label: 'Stories referring to this concept',
    },
  ],
}

I get the exact same errors as with snake case. Interestingly, the build shows the Invalid join field error, but doesn't fail. Here is the build output:

> [email protected] build /workspaces/codespaces-blank/join-test
> cross-env NODE_OPTIONS=--no-deprecation next build

   ▲ Next.js 15.0.3
   - Environments: .env
   - Experiments (use with caution):
     · turbo

   Creating an optimized production build ...
 ✓ Compiled successfully
 ✓ Linting and checking validity of types    
   Collecting page data  ._: Invalid join field storiesConnections. The config does not have a field 'conceptsArray.relatedConcept' in collection 'stories'.
    at k (/workspaces/codespaces-blank/join-test/.next/server/chunks/336.js:309:81782)
    at C (/workspaces/codespaces-blank/join-test/.next/server/chunks/336.js:309:82642)
    at H (/workspaces/codespaces-blank/join-test/.next/server/chunks/336.js:309:55877)
    at eg (/workspaces/codespaces-blank/join-test/.next/server/chunks/336.js:309:69102)
    at async ey (/workspaces/codespaces-blank/join-test/.next/server/chunks/336.js:309:69802) {
  data: null,
  isOperational: true,
  isPublic: false,
  status: 500,
  [cause]: null
}
 ✓ Collecting page data    
 ✓ Generating static pages (6/6)
_: Invalid join field storiesConnections. The config does not have a field 'conceptsArray.relatedConcept' in collection 'stories'.
    at k (/workspaces/codespaces-blank/join-test/.next/server/chunks/336.js:309:81782)
    at C (/workspaces/codespaces-blank/join-test/.next/server/chunks/336.js:309:82642)
    at H (/workspaces/codespaces-blank/join-test/.next/server/chunks/336.js:309:55877)
    at eg (/workspaces/codespaces-blank/join-test/.next/server/chunks/336.js:309:69102)
    at async ey (/workspaces/codespaces-blank/join-test/.next/server/chunks/336.js:309:69802) {
  data: null,
  isOperational: true,
  isPublic: false,
  status: 500,
  [cause]: null
}
 ✓ Collecting build traces    
 ✓ Finalizing page optimization    

Route (app)                              Size     First Load JS
┌ ○ /_not-found                          904 B           102 kB
├ ƒ /admin/[[...segments]]               339 B           501 kB
├ ƒ /api/[...slug]                       540 B           101 kB
├ ƒ /api/graphql                         518 B           101 kB
├ ƒ /api/graphql-playground              540 B           101 kB
└ ƒ /my-route                            518 B           101 kB
+ First Load JS shared by all            101 kB
  ├ chunks/7883-a4c01db332449891.js      45.8 kB
  ├ chunks/8de28dba-eee98e144acd422f.js  52.5 kB
  └ other shared chunks (total)          2.57 kB


○  (Static)   prerendered as static content
ƒ  (Dynamic)  server-rendered on demand

[akhrarovsaid]

I'm not sure how Joins are supposed to work with array fields, but technically the error is right here - there is no such field at path 'conceptsArray.relatedConcept'. I think you would have to do something along the lines of 'conceptsArray.[0].relatedConcept' or something along those lines that might give it an index to work with?

[Because789]

Just tested conceptsArray.[0].relatedConcept, same error. I tried conceptsArray.relatedConcept[0] before, also same error.

[r1tsuu]

Yeah I'm sure the Join Field doesn't work if the relationship field is nested to an array/blocks. Only with groups / tabs
What you could do instead of the conceptsArray array field is to have "junction" StoryConceptConnections collection:

export const Stories: CollectionConfig = {
  slug: 'stories',
  fields: [
    {
      name: 'connections',
      type: 'join',
      collection: 'story-concept-connections',
      on: 'story',
    },
  ],
}

// Replacement of conceptsArray. This has both references to the concept and story.
export const StoryConceptConnections = {
  slug: 'story-concept-connections',
  fields: [
    {
      name: 'story',
      type: 'relationship',
      relationTo: 'stories',
      required: true,
    },
    {
      name: 'concept',
      type: 'relationship',
      relationTo: 'concepts',
      required: true,
    },
  ],
}

export const Concepts: CollectionConfig = {
  slug: 'concepts',
  fields: [
    {
      name: 'conceptName',
      type: 'text',
    },
    {
      name: 'storiesConnections',
      type: 'join',
      collection: 'story-concept-connections',
      label: 'Stories referring to this concept',
      on: 'concept',
    },
  ],
}

[Because789]

I thought about that, and it looks like a solid solution I can work with. But it opened a new can of worms: lots of server errors (mainly header errors x-forwarded-host header with value X does not match origin header with value localhost:3000. I decided to test it not only in Codespaces, but locally, too, and there are no issues here. So for the record, this project builds properly, works locally, but doesn't in Codespaces: https://github.com/Because789/join-con-test.

@DanRibbens, I made a little PR to improve the join field docs: #9768

[DanRibbens]

I think we should support joining with a reletionship inside of an array. It did work at one point in my development of this feature. I should have included a test for this because I consider it a regression now.
We support relationship with hasMany which is effectively the same as this.

I'm not going to merge #9768 because I want to try to get this working again.

[Because789]

That sounds much better to me, than merely an addition to the docs! I'm gonna close the PR, but please don't forget to remove the asterisks behind the where config option. Good luck!

[DanRibbens]

I have a draft PR #9773. It works for mongodb but drizzle needs a little more work.

[Because789]

Fix is included in https://github.com/payloadcms/payload/releases/tag/v3.9.0 (PR #9773). I need to find some time to test it and gonna close this discussion after that...

[DanRibbens]

Yeah, it should be all working now. Thanks!