Relationships

GraphJin relationship traversal comes from schema metadata. Foreign keys, configured relationships, embedded JSON virtual tables, remote API joins, and database-join edges all become nested GraphQL selections, but they are not all executed the same way.

Parent and child traversal

query {
  products(limit: 3, order_by: { id: asc }) {
    id
    owner {
      id
      email
    }
  }
}

Relationships come from database schema discovery and explicit table configuration.

Related filters and ordering

Filters and ordering can target relationship paths when the path is known.

query {
  products(
    where: { owner: { id: { or: [{ eq: $user_id }, { eq: 3 }] } } }
    order_by: { users: { email: desc }, id: desc }
    limit: 5
  ) {
    id
    owner { id email }
  }
}

Many-to-many

Join tables can expose many-to-many paths without user-written resolver code.

query {
  products(limit: 2, order_by: { id: asc }) {
    id
    customers {
      id
      email
    }
  }
}

When more than one join table or foreign key path is possible, use @through(table:) or @through(column:) to disambiguate. Agents should discover relationship rows in gj_catalog before guessing.

Recursive relationships

Self-referential tables can model trees such as comments and categories.

query {
  comments(id: $id) {
    id
    body
    replies: comments(find: "children") {
      id
      body
    }
  }
}

Polymorphic relationships

Union-style selections let GraphJin expose polymorphic subjects.

query {
  comments {
    id
    subject {
      ... on products {
        id
        name
      }
      ... on users {
        id
        email
      }
    }
  }
}

MongoDB relationships

MongoDB relationships are not SQL joins. GraphJin emits JSON DSL and the MongoDB driver translates related selections to aggregation pipeline $lookup stages.

{
  "$lookup": {
    "from": "products",
    "let": { "userId": "$_id" },
    "pipeline": [
      { "$match": { "$expr": { "$eq": ["$owner_id", "$$userId"] } } }
    ],
    "as": "products"
  }
}

Array-column joins use $in; embedded JSON virtual tables use $unwind, $lookup, and $group rather than a simple lookup.

Nested database joins

Cross-source joins preserve the same GraphQL shape but use different execution phases:

1. Compile and execute the parent query against its source.
2. Keep a placeholder field such as __orders_db_join in the parent JSON.
3. Extract the parent key from the result.
4. Build a child query such as orders(where: { user_id: { eq: 42 } }).
5. Execute that child query with the target source’s compiler and connection.
6. Replace the placeholder with the child JSON.

That model is why same-database joins are usually cheaper than cross-database joins, and why table/source ownership should be explicit in multi-source deployments.