⚡

高级查询过滤Skill bknd-query-filter

这个技能用于在Bknd平台中构建复杂的查询过滤条件，支持多种运算符（如$eq、$like、$in）和逻辑组合（如AND、OR），适用于动态查询构建、数据检索和后端开发。关键词：Bknd, 查询过滤, 高级查询, 数据操作, 后端开发, 低代码, 数据库查询, API集成。

低代码开发 0 次安装 0 次浏览 更新于 3/8/2026

name: bknd-query-filter description: 在Bknd中构建具有复杂过滤条件的高级查询时使用。涵盖所有过滤运算符（$eq、$ne、$gt、$lt、$like、$ilike、$in、$nin、$isnull、$between）、逻辑运算符（$or、$and）、嵌套条件、组合过滤器和动态查询构建。

高级查询过滤

在Bknd中构建具有多个条件、逻辑运算符和动态过滤器的复杂查询。

先决条件

  • Bknd项目运行中（本地或部署）
  • 实体存在且包含数据
  • SDK配置完成或已知API端点
  • 基本了解readMany（参见bknd-crud-read）

何时使用UI模式

  • 编码前测试过滤组合
  • 探索数据模式
  • 快速临时查询

UI步骤： 管理面板 > 数据 > 选择实体 > 使用过滤控件

何时使用代码模式

  • 复杂多条件查询
  • 动态用户驱动过滤器（搜索、面）
  • 可重用的查询构建器
  • API集成

代码方法

步骤1：了解运算符类别

Bknd支持以下过滤运算符：

类别 运算符
相等性 $eq, $ne
比较 $gt, $gte, $lt, $lte
范围 $between
模式匹配 $like, $ilike
数组 $in, $nin（别名：$notin）
空值 $isnull
逻辑 $or, $and（隐式）

步骤2：使用比较运算符

import { Api } from "bknd";
const api = new Api({ host: "http://localhost:7654" });

// 相等性（隐式$eq）
const { data } = await api.data.readMany("products", {
  where: { status: "active" },  // 等同于 { status: { $eq: "active" } }
});

// 不相等
const { data } = await api.data.readMany("products", {
  where: { status: { $ne: "deleted" } },
});

// 数值比较
const { data } = await api.data.readMany("products", {
  where: {
    price: { $gte: 10 },   // price >= 10
    stock: { $gt: 0 },     // stock > 0
  },
});

// 日期比较
const { data } = await api.data.readMany("orders", {
  where: {
    created_at: { $gte: "2024-01-01" },
    created_at: { $lt: "2024-02-01" },
  },
});

步骤3：使用范围运算符（$between）

// 价格在10到100之间（包含）
const { data } = await api.data.readMany("products", {
  where: {
    price: { $between: [10, 100] },
  },
});

// 日期范围
const { data } = await api.data.readMany("orders", {
  where: {
    created_at: { $between: ["2024-01-01", "2024-12-31"] },
  },
});

步骤4：使用模式匹配

// LIKE（区分大小写）- 使用%作为通配符
const { data } = await api.data.readMany("posts", {
  where: { title: { $like: "%React%" } },
});

// ILIKE（不区分大小写）- 推荐用于搜索
const { data } = await api.data.readMany("posts", {
  where: { title: { $ilike: "%react%" } },
});

// 以...开始
const { data } = await api.data.readMany("users", {
  where: { name: { $like: "John%" } },
});

// 以...结束
const { data } = await api.data.readMany("users", {
  where: { email: { $like: "%@gmail.com" } },
});

// 通配符替代：使用*代替%
const { data } = await api.data.readMany("posts", {
  where: { title: { $like: "*React*" } },  // 转换为%React%
});

步骤5：使用数组运算符

// 在数组中 - 匹配任何值
const { data } = await api.data.readMany("posts", {
  where: { status: { $in: ["published", "featured"] } },
});

// 不在数组中 - 排除值
const { data } = await api.data.readMany("posts", {
  where: { status: { $nin: ["deleted", "archived"] } },
});

// 按ID获取特定记录
const { data } = await api.data.readMany("products", {
  where: { id: { $in: [1, 5, 10, 15] } },
});

步骤6：使用空值检查

// 是NULL
const { data } = await api.data.readMany("posts", {
  where: { deleted_at: { $isnull: true } },
});

// 不是NULL
const { data } = await api.data.readMany("posts", {
  where: { published_at: { $isnull: false } },
});

// 组合：活动记录（未删除，已发布）
const { data } = await api.data.readMany("posts", {
  where: {
    deleted_at: { $isnull: true },
    published_at: { $isnull: false },
  },
});

步骤7：与AND组合（隐式）

同一级别的多个字段 = AND：

// status = "published" AND category = "news" AND views > 100
const { data } = await api.data.readMany("posts", {
  where: {
    status: { $eq: "published" },
    category: { $eq: "news" },
    views: { $gt: 100 },
  },
});

步骤8：使用OR条件

// status = "published" OR featured = true
const { data } = await api.data.readMany("posts", {
  where: {
    $or: [
      { status: { $eq: "published" } },
      { featured: { $eq: true } },
    ],
  },
});

// 多个OR条件
const { data } = await api.data.readMany("users", {
  where: {
    $or: [
      { role: { $eq: "admin" } },
      { role: { $eq: "moderator" } },
      { is_verified: { $eq: true } },
    ],
  },
});

步骤9：组合AND + OR

// category = "news" AND (status = "published" OR author_id = currentUser)
const { data } = await api.data.readMany("posts", {
  where: {
    category: { $eq: "news" },
    $or: [
      { status: { $eq: "published" } },
      { author_id: { $eq: currentUserId } },
    ],
  },
});

// 复杂：(price < 50 OR on_sale = true) AND in_stock = true AND category IN ["electronics", "books"]
const { data } = await api.data.readMany("products", {
  where: {
    in_stock: { $eq: true },
    category: { $in: ["electronics", "books"] },
    $or: [
      { price: { $lt: 50 } },
      { on_sale: { $eq: true } },
    ],
  },
});

步骤10：按相关字段过滤（连接）

使用join通过相关实体中的字段过滤：

// 作者角色为"admin"的帖子
const { data } = await api.data.readMany("posts", {
  join: ["author"],
  where: {
    "author.role": { $eq: "admin" },
  },
});

// 客户国家为"US"且产品类别为"electronics"的订单
const { data } = await api.data.readMany("orders", {
  join: ["customer", "product"],
  where: {
    "customer.country": { $eq: "US" },
    "product.category": { $eq: "electronics" },
  },
});

// 与常规过滤器组合
const { data } = await api.data.readMany("posts", {
  join: ["author"],
  where: {
    status: { $eq: "published" },
    "author.is_verified": { $eq: true },
  },
});

动态查询构建

编程方式构建查询

type WhereClause = Record<string, any>;

function buildProductQuery(filters: {
  search?: string;
  minPrice?: number;
  maxPrice?: number;
  categories?: string[];
  inStock?: boolean;
}): WhereClause {
  const where: WhereClause = {};

  if (filters.search) {
    where.name = { $ilike: `%${filters.search}%` };
  }

  if (filters.minPrice !== undefined) {
    where.price = { ...where.price, $gte: filters.minPrice };
  }

  if (filters.maxPrice !== undefined) {
    where.price = { ...where.price, $lte: filters.maxPrice };
  }

  if (filters.categories?.length) {
    where.category = { $in: filters.categories };
  }

  if (filters.inStock !== undefined) {
    where.stock = filters.inStock ? { $gt: 0 } : { $eq: 0 };
  }

  return where;
}

// 使用
const filters = { search: "laptop", minPrice: 500, categories: ["electronics"] };
const { data } = await api.data.readMany("products", {
  where: buildProductQuery(filters),
  sort: { price: "asc" },
  limit: 20,
});

条件OR构建器

function buildOrConditions(conditions: WhereClause[]): WhereClause {
  const validConditions = conditions.filter(c => Object.keys(c).length > 0);

  if (validConditions.length === 0) return {};
  if (validConditions.length === 1) return validConditions[0];

  return { $or: validConditions };
}

// 跨多个字段搜索
const searchTerm = "john";
const { data } = await api.data.readMany("users", {
  where: buildOrConditions([
    { name: { $ilike: `%${searchTerm}%` } },
    { email: { $ilike: `%${searchTerm}%` } },
    { username: { $ilike: `%${searchTerm}%` } },
  ]),
});

面搜索模式

type Facets = {
  category?: string;
  brand?: string;
  priceRange?: "budget" | "mid" | "premium";
  rating?: number;
};

const PRICE_RANGES = {
  budget: { $lt: 50 },
  mid: { $between: [50, 200] },
  premium: { $gt: 200 },
};

async function facetedSearch(query: string, facets: Facets) {
  const where: WhereClause = {};

  // 文本搜索
  if (query) {
    where.name = { $ilike: `%${query}%` };
  }

  // 面过滤器
  if (facets.category) {
    where.category = { $eq: facets.category };
  }

  if (facets.brand) {
    where.brand = { $eq: facets.brand };
  }

  if (facets.priceRange) {
    where.price = PRICE_RANGES[facets.priceRange];
  }

  if (facets.rating) {
    where.rating = { $gte: facets.rating };
  }

  return api.data.readMany("products", { where, limit: 50 });
}

React集成

搜索过滤组件

import { useState, useCallback } from "react";
import { useApp } from "bknd/react";
import useSWR from "swr";
import { useDebouncedValue } from "@mantine/hooks";

type Filters = {
  search: string;
  status: string;
  minDate: string;
};

function FilteredList() {
  const { api } = useApp();
  const [filters, setFilters] = useState<Filters>({
    search: "",
    status: "",
    minDate: "",
  });
  const [debouncedFilters] = useDebouncedValue(filters, 300);

  const buildWhere = useCallback((f: Filters) => {
    const where: Record<string, any> = {};

    if (f.search) {
      where.title = { $ilike: `%${f.search}%` };
    }
    if (f.status) {
      where.status = { $eq: f.status };
    }
    if (f.minDate) {
      where.created_at = { $gte: f.minDate };
    }

    return where;
  }, []);

  const { data: posts, isLoading } = useSWR(
    ["posts", debouncedFilters],
    () => api.data.readMany("posts", {
      where: buildWhere(debouncedFilters),
      sort: { created_at: "desc" },
      limit: 20,
    }).then(r => r.data)
  );

  return (
    <div>
      <input
        placeholder="搜索..."
        value={filters.search}
        onChange={e => setFilters(f => ({ ...f, search: e.target.value }))}
      />
      <select
        value={filters.status}
        onChange={e => setFilters(f => ({ ...f, status: e.target.value }))}
      >
        <option value="">所有状态</option>
        <option value="draft">草稿</option>
        <option value="published">已发布</option>
      </select>
      <input
        type="date"
        value={filters.minDate}
        onChange={e => setFilters(f => ({ ...f, minDate: e.target.value }))}
      />

      {isLoading ? <p>加载中...</p> : (
        <ul>
          {posts?.map(post => <li key={post.id}>{post.title}</li>)}
        </ul>
      )}
    </div>
  );
}

REST API方法

查询字符串格式

# 简单过滤器
curl "http://localhost:7654/api/data/posts?where=%7B%22status%22%3A%22published%22%7D"

# URL解码：where={"status":"published"}

通过POST的复杂查询

对于复杂查询，使用POST到/api/data/:entity/query：

curl -X POST http://localhost:7654/api/data/posts/query \
  -H "Content-Type: application/json" \
  -d '{
    "where": {
      "category": {"$eq": "news"},
      "$or": [
        {"status": {"$eq": "published"}},
        {"featured": {"$eq": true}}
      ]
    },
    "sort": {"created_at": "desc"},
    "limit": 20
  }'

完整示例

import { Api } from "bknd";

const api = new Api({ host: "http://localhost:7654" });

// 1. 简单相等性过滤器
const published = await api.data.readMany("posts", {
  where: { status: "published" },
});

// 2. 数值范围
const midPriced = await api.data.readMany("products", {
  where: { price: { $between: [50, 200] } },
});

// 3. 文本搜索（不区分大小写）
const searchResults = await api.data.readMany("products", {
  where: { name: { $ilike: "%laptop%" } },
});

// 4. 多个值
const specificCategories = await api.data.readMany("products", {
  where: { category: { $in: ["electronics", "computers"] } },
});

// 5. 排除软删除
const activeRecords = await api.data.readMany("posts", {
  where: { deleted_at: { $isnull: true } },
});

// 6. 复杂AND + OR
const complexQuery = await api.data.readMany("orders", {
  where: {
    created_at: { $gte: "2024-01-01" },
    status: { $nin: ["cancelled", "refunded"] },
    $or: [
      { total: { $gt: 100 } },
      { is_priority: { $eq: true } },
    ],
  },
  sort: { created_at: "desc" },
  limit: 50,
});

// 7. 按相关实体过滤
const adminPosts = await api.data.readMany("posts", {
  join: ["author"],
  where: {
    "author.role": { $eq: "admin" },
    status: { $eq: "published" },
  },
});

常见陷阱

错误组合相同字段运算符

问题： 覆盖先前条件。

// 错误 - 第二次赋值覆盖第一次
where: {
  price: { $gte: 10 },
  price: { $lte: 100 },  // 覆盖！
}

// 正确 - 使用$between或展开
where: {
  price: { $between: [10, 100] },
}
// 或
where: {
  price: { $gte: 10, $lte: 100 },
}

$or在错误级别

问题： $or必须在where子句的顶级。

// 错误 - 嵌套$or
where: {
  status: {
    $or: [{ $eq: "a" }, { $eq: "b" }],  // 无效！
  },
}

// 正确 - 对于相同字段使用$in
where: {
  status: { $in: ["a", "b"] },
}

// 正确 - 对于不同字段，$or在顶级
where: {
  $or: [
    { status: { $eq: "a" } },
    { featured: { $eq: true } },
  ],
}

相关字段过滤缺少Join

问题： 过滤相关字段没有join。

// 错误 - 不会工作
where: { "author.role": { $eq: "admin" } }

// 正确 - 添加join
{
  join: ["author"],
  where: { "author.role": { $eq: "admin" } },
}

区分大小写搜索

问题： $like区分大小写。

// 可能错过结果
where: { title: { $like: "%React%" } }

// 使用$ilike进行不区分大小写搜索
where: { title: { $ilike: "%react%" } }

空过滤器对象

问题： 空where返回所有记录。

// 返回所有内容（无过滤器）
where: {}

// 始终验证过滤器存在
const where = buildFilters(userInput);
if (Object.keys(where).length === 0) {
  // 处理：显示默认视图或要求至少一个过滤器
}

验证

首先在管理面板测试过滤器：

  1. 管理面板 > 数据 > 选择实体
  2. 使用过滤器控件构建查询
  3. 验证预期结果
  4. 翻译为代码

或记录where子句：

const where = buildFilters(input);
console.log("查询:", JSON.stringify(where, null, 2));
const { data } = await api.data.readMany("posts", { where });

建议和避免

建议：

  • 用户界面搜索使用$ilike（不区分大小写）
  • 相同字段使用$in而不是多个$or
  • 数值/日期范围使用$between
  • 为过滤器UI动态构建查询
  • 构建查询前验证/清理用户输入
  • 过滤相关字段时使用join

避免：

  • 用户搜索使用$like（区分大小写问题）
  • 在字段条件内嵌套$or
  • 忘记相关字段过滤的join
  • 直接信任用户输入在查询中
  • 构建过于复杂的嵌套条件
  • 忘记空where = 返回所有

相关技能

  • bknd-crud-read - 基本读取操作
  • bknd-pagination - 分页过滤结果
  • bknd-define-relationship - 设置关系以进行连接过滤
  • bknd-row-level-security - 通过策略应用自动过滤器