supabase 不支持传统 sql 的显式 join 语法，而是通过从关联表（如 `usuario_empresa`）出发，使用嵌套选择（foreign table syntax）来实现多表数据拉取。本文详解如何正确转换三表联查 sql 到 supabase 客户端代码，并避免常见错误。
在 Supabase 中，不能对主表（如 'usuario'）调用 .join() 方法——这是导致你遇到语法错误的根本原因。Supabase 的 JavaScript/TypeScript 客户端 SDK 不提供 .join() 链式方法（该方法在旧版或某些社区误传中被虚构），官方 API 仅支持通过 select() 中的关系路径语法（Foreign Table Syntax） 实现关联查询。
正确的做法是：以中间表 usuario_empresa 为查询起点，利用其外键字段 usuario_id 和 empresa_id，分别“展开”关联的 usuario 和 empresa 表数据。这本质上是一种嵌套对象投影（nested object selection），而非 SQL JOIN。
✅ 正确代码如下：
const { data, error } = await supabase
.from('usuario_empresa')
.select(`
usuario:usuario_id (
id,
nome,
email,
telefone,
data_nascimento,
cidade_nascimento
),
empresa:empresa_id (
id,
nome,
cnpj,
endereco
)
`);执行后，返回的数据结构形如：
[
{
"usuario": { "id": 1, "nome": "João", "email": "joao@example.com", ... },
"empresa": { "id": 101, "nome": "Tech S/A", "cnpj": "12.345.678/0001-90", ... }
}
]⚠️ 注意事项：
- 表名前无需加 public. 前缀（Supabase 默认使用 public schema，且不支持在查询中显式指定 schema）；
- 关系别名语法格式为：
: ( )，其中 usuario:usuario_id 表示“将 usuario_id 字段作为外键，关联到 usuario 表”； - 若 usuario_empresa 表自身有主键（如自增 id），你可一并查询：
.select(`id, usuario:usuario_id (id, nome), empresa:empresa_id (id, nome)`)
- 确保数据库中已为外键字段（usuario_id, empresa_id）创建了 Row Level Security (RLS) 策略，否则可能因权限问题返回空数组或报错；
- 如需过滤条件（例如只查某用户所属企业），可在 .select() 后链式调用 .eq('usuario_id', 123)。
? 小结：Supabase 的关联查询逻辑是「以关系表为中心，向外展开」，而非「以主表为中心，向内 JOIN」。掌握这一范式转换，即可高效、安全地实现一对多、多对多等复杂关系的数据获取。
