本文详解如何在 Supabase 中通过单次查询，使用 ilike 同时模糊匹配主表（如 foods）和外键关联表（如 brands）的字段，避免多次请求，提升性能与代码简洁性。
本文详解如何在 supabase 中通过单次查询，使用 `ilike` 同时模糊匹配主表（如 `foods`）和外键关联表（如 `brands`）的字段，避免多次请求，提升性能与代码简洁性。
在 Supabase（底层基于 PostgREST）中，若需对主表字段（如 foods.product_name）和其关联的外键表字段（如 brands.brand_name）同时进行大小写不敏感的模糊搜索（ilike），不能直接在 .select() 后链式调用多个 .eq() 或 .ilike()——因为关联字段（如 brand_name）属于嵌套对象，需借助 PostgREST 的 or 过滤器 + 原生字段路径语法 实现。
核心方案是使用 .or() 方法，并传入符合 PostgREST 规范的逻辑表达式字符串。该字符串支持跨表字段引用，格式为：
"field1.operator.'value',field2.operator.'value'"
✅ 正确示例（搜索关键词 "Paprykarz"）：
const searchTerm = "Paprykarz";
const { data, error } = await supabase
.from('foods')
.select(`
id,
product_name,
brands(brand_name),
barcode,
serving_factor,
units(unit),
calories, fat, saturated_fat, carbohydrates, sugar, protein, salt,
image,
vegan, lactose_free, gluten_free,
source
`)
.or(`product_name.ilike.%${searchTerm}%,brands.brand_name.ilike.%${searchTerm}%`);⚠️ 关键细节说明：
- 关联字段必须使用点号路径语法：brands.brand_name（而非 brands(brand_name) 中的别名）；
- ilike 的通配符 % 需直接拼接在值两侧，且整个值要用英文双引号包裹（PostgREST 要求），但 Supabase JS 客户端会自动处理引号转义，因此只需写 %${searchTerm}%；
- .or() 内部是逻辑或关系，即匹配 product_name 或 brand_name 包含关键词的记录；
- 该查询等价于 SQL：
SELECT * FROM foods JOIN brands ON foods.brand = brands.id WHERE foods.product_name ILIKE '%Paprykarz%' OR brands.brand_name ILIKE '%Paprykarz%';
? 安全提醒（重要！）：
直接拼接用户输入到 .or() 字符串中存在 SQL 注入风险（尽管 PostgREST 有基础防护，但不可依赖）。务必对 searchTerm 进行净化：
- 使用正则移除控制字符、SQL 元字符（如 ;, --, /*, */, \0）；
- 或更推荐：启用 Supabase 的 Row Level Security (RLS) 并结合服务端函数封装查询逻辑；
- 参考社区讨论：Supabase Discussions #3843。
? 扩展技巧：
若需“且”逻辑（同时匹配品名 和 品牌），可改用 .match() 配合预计算字段，或在数据库侧创建物化视图/自定义函数；但多数场景下 or 已满足“任一字段命中即返回”的业务需求。
综上，.or() 是实现跨表 ilike 联合搜索最简洁、高效的方式——无需拆分为两次请求，也无需复杂 join 手动构造，真正发挥 Supabase 的声明式查询优势。
