entgo

README

列表查询规则

通用列表查询请求

字段名	类型	格式	字段描述	示例	备注
page	number		当前页码		默认为1，最小值为1。
pageSize	number		每页的行数		默认为10，最小值为1。
query	string	json object 或 json object array	AND过滤条件	json字符串: {"field1":"val1","field2":"val2"} 或者[{"field1":"val1"},{"field1":"val2"},{"field2":"val2"}]	map和array都支持，当需要同字段名，不同值的情况下，请使用array。具体规则请见：过滤规则
or	string	json object 或 json object array	OR过滤条件	同 AND过滤条件
orderBy	string	json string array	排序条件	json字符串：["-create_time", "type"]	json的string array，字段名前加-是为降序，不加为升序。具体规则请见：排序规则
noPaging	boolean		是否不分页		此字段为true时，page、pageSize字段的传入将无效用。
fieldMask	string	其语法为使用逗号分隔字段名	字段掩码	例如：id,realName,userName。	此字段是SELECT条件，为空的时候是为*。

排序规则

排序操作本质上是SQL里面的Order By条件。

序列	示例	备注
升序	["type"]
降序	["-create_time"]	字段名前加-是为降序

过滤规则

过滤器操作本质上是SQL里面的WHERE条件。

过滤器的规则，遵循了Python的ORM的规则，比如：

• Tortoise ORM Filtering。
• Django Field lookups

如果只是普通的查询，只需要传递字段名即可，但是如果需要一些特殊的查询，那么就需要加入操作符了。

特殊查询的语法规则其实很简单，就是使用双下划线__分割字段名和操作符：

{字段名}__{查找类型} : {值}
{字段名}.{JSON字段名}__{查找类型} : {值}

查找类型	示例	SQL	备注
not	{"name__not" : "tom"}	WHERE NOT ("name" = "tom")
in	{"name__in" : "[\"tom\", \"jimmy\"]"}	WHERE name IN ("tom", "jimmy")
not_in	{"name__not_in" : "[\"tom\", \"jimmy\"]"}	WHERE name NOT IN ("tom", "jimmy")
gte	{"create_time__gte" : "2023-10-25"}	WHERE "create_time" >= "2023-10-25"
gt	{"create_time__gt" : "2023-10-25"}	WHERE "create_time" > "2023-10-25"
lte	{"create_time__lte" : "2023-10-25"}	WHERE "create_time" <= "2023-10-25"
lt	{"create_time__lt" : "2023-10-25"}	WHERE "create_time" < "2023-10-25"
range	{"create_time__range" : "[\"2023-10-25\", \"2024-10-25\"]"}	WHERE "create_time" BETWEEN "2023-10-25" AND "2024-10-25" 或 WHERE "create_time" >= "2023-10-25" AND "create_time" <= "2024-10-25"	需要注意的是: 1. 有些数据库的BETWEEN实现的开闭区间可能不一样。 2. 日期2005-01-01会被隐式转换为：2005-01-01 00:00:00，两个日期一致就会导致查询不到数据。
isnull	{"name__isnull" : "True"}	WHERE name IS NULL
not_isnull	{"name__not_isnull" : "False"}	WHERE name IS NOT NULL
contains	{"name__contains" : "L"}	WHERE name LIKE '%L%';
icontains	{"name__icontains" : "L"}	WHERE name ILIKE '%L%';
startswith	{"name__startswith" : "La"}	WHERE name LIKE 'La%';
istartswith	{"name__istartswith" : "La"}	WHERE name ILIKE 'La%';
endswith	{"name__endswith" : "a"}	WHERE name LIKE '%a';
iendswith	{"name__iendswith" : "a"}	WHERE name ILIKE '%a';
exact	{"name__exact" : "a"}	WHERE name LIKE 'a';
iexact	{"name__iexact" : "a"}	WHERE name ILIKE 'a';
regex	{"title__regex" : "^(An?|The) +"}	MySQL: WHERE title REGEXP BINARY '^(An?|The) +' Oracle: WHERE REGEXP_LIKE(title, '^(An?|The) +', 'c'); PostgreSQL: WHERE title ~ '^(An?|The) +'; SQLite: WHERE title REGEXP '^(An?|The) +';
iregex	{"title__iregex" : "^(an?|the) +"}	MySQL: WHERE title REGEXP '^(an?|the) +' Oracle: WHERE REGEXP_LIKE(title, '^(an?|the) +', 'i'); PostgreSQL: WHERE title ~* '^(an?|the) +'; SQLite: WHERE title REGEXP '(?i)^(an?|the) +';
search

以及将日期提取出来的查找类型：

查找类型	示例	SQL	备注
date	{"pub_date__date" : "2023-01-01"}	WHERE DATE(pub_date) = '2023-01-01'
year	{"pub_date__year" : "2023"}	WHERE EXTRACT('YEAR' FROM pub_date) = '2023'	哪一年
iso_year	{"pub_date__iso_year" : "2023"}	WHERE EXTRACT('ISOYEAR' FROM pub_date) = '2023'	ISO 8601 一年中的周数
month	{"pub_date__month" : "12"}	WHERE EXTRACT('MONTH' FROM pub_date) = '12'	月份，1-12
day	{"pub_date__day" : "3"}	WHERE EXTRACT('DAY' FROM pub_date) = '3'	该月的某天(1-31)
week	{"pub_date__week" : "7"}	WHERE EXTRACT('WEEK' FROM pub_date) = '7'	ISO 8601 周编号 一年中的周数
week_day	{"pub_date__week_day" : "tom"}	``	星期几
iso_week_day	{"pub_date__iso_week_day" : "tom"}	``
quarter	{"pub_date__quarter" : "1"}	WHERE EXTRACT('QUARTER' FROM pub_date) = '1'	一年中的季度
time	{"pub_date__time" : "12:59:59"}	``
hour	{"pub_date__hour" : "12"}	WHERE EXTRACT('HOUR' FROM pub_date) = '12'	小时(0-23)
minute	{"pub_date__minute" : "59"}	WHERE EXTRACT('MINUTE' FROM pub_date) = '59'	分钟 (0-59)
second	{"pub_date__second" : "59"}	WHERE EXTRACT('SECOND' FROM pub_date) = '59'	秒 (0-59)

Documentation

Index

• Constants
• func ApplyFieldMaskSelect(apply func(...string), mask *fieldmaskpb.FieldMask)
• func ApplyFieldMaskToBuilder[R any, B interface{ ... }](builder B, mask *fieldmaskpb.FieldMask) (R, bool)
• func BuildFieldSelect(s *sql.Selector, fields []string)
• func BuildFieldSelector(fields []string) (error, func(s *sql.Selector))
• func BuildFilterSelector(andFilterJsonString, orFilterJsonString string) (error, []func(s *sql.Selector))
• func BuildOrderSelect(s *sql.Selector, field string, desc bool)
• func BuildOrderSelector(orderBys []string, defaultOrderField string) (error, func(s *sql.Selector))
• func BuildPaginationSelect(s *sql.Selector, page, pageSize int32)
• func BuildPaginationSelector(page, pageSize int32, noPaging bool) func(*sql.Selector)
• func BuildQuerySelector(andFilterJsonString, orFilterJsonString string, page, pageSize int32, ...) (err error, whereSelectors []func(s *sql.Selector), ...)
• func NormalizeFieldMaskPaths(fm *fieldmaskpb.FieldMask)
• func NormalizePaths(paths []string) []string
• func QueryCommandToOrderConditions(orderBys []string) (error, func(s *sql.Selector))
• func QueryCommandToWhereConditions(strJson string, isOr bool) (error, func(s *sql.Selector))
• type DatePart
• type FilterOp

Constants

const (
	QueryDelimiter     = "__" // 分隔符
	JsonFieldDelimiter = "."  // JSONB字段分隔符
)

Functions

func ApplyFieldMaskSelect

func ApplyFieldMaskSelect(apply func(...string), mask *fieldmaskpb.FieldMask)

ApplyFieldMaskSelect 将 fieldmask 转换为 snake_case 并通过 apply 回调传入。 - apply: 接受归一化字段并调用，例如: func(ps ...string) { builder.Select(ps...) } - mask: 传入的 FieldMask，nil 或 空时不做任何操作

func ApplyFieldMaskToBuilder

func ApplyFieldMaskToBuilder[R any, B interface{ Select(fields ...string) R }](builder B, mask *fieldmaskpb.FieldMask) (R, bool)

ApplyFieldMaskToBuilder 接受一个带 Select(...string) 方法的 builder 和 FieldMask， 将 paths 归一化为 snake_case（并将 id_/_id 归为 id），然后调用 builder.Select(paths...) 并返回 builder。 - R 是 Select 方法的返回类型（例如 *ent.UserSelect） - B 是拥有 Select(...string) R 方法的类型（例如 *ent.UserQuery） 返回 (R, bool): bool 表示是否实际调用了 Select（即 mask 非空）。

func BuildFieldSelect

func BuildFieldSelect(s *sql.Selector, fields []string)

BuildFieldSelect 构建字段选择

func BuildFieldSelector

func BuildFieldSelector(fields []string) (error, func(s *sql.Selector))

BuildFieldSelector 构建字段选择器

func BuildFilterSelector

func BuildFilterSelector(andFilterJsonString, orFilterJsonString string) (error, []func(s *sql.Selector))

BuildFilterSelector 构建过滤选择器

func BuildOrderSelect

func BuildOrderSelect(s *sql.Selector, field string, desc bool)

func BuildOrderSelector

func BuildOrderSelector(orderBys []string, defaultOrderField string) (error, func(s *sql.Selector))

func BuildPaginationSelect

func BuildPaginationSelect(s *sql.Selector, page, pageSize int32)

func BuildPaginationSelector

func BuildPaginationSelector(page, pageSize int32, noPaging bool) func(*sql.Selector)

func BuildQuerySelector

func BuildQuerySelector(
	andFilterJsonString, orFilterJsonString string,
	page, pageSize int32, noPaging bool,
	orderBys []string, defaultOrderField string,
	selectFields []string,
) (err error, whereSelectors []func(s *sql.Selector), querySelectors []func(s *sql.Selector))

BuildQuerySelector 构建分页过滤查询器

func NormalizeFieldMaskPaths

func NormalizeFieldMaskPaths(fm *fieldmaskpb.FieldMask)

NormalizeFieldMaskPaths normalizes the paths in the given FieldMask to snake_case

func NormalizePaths

func NormalizePaths(paths []string) []string

func QueryCommandToOrderConditions

func QueryCommandToOrderConditions(orderBys []string) (error, func(s *sql.Selector))

QueryCommandToOrderConditions 查询命令转换为排序条件

func QueryCommandToWhereConditions

func QueryCommandToWhereConditions(strJson string, isOr bool) (error, func(s *sql.Selector))

QueryCommandToWhereConditions 查询命令转换为选择条件

Types

type DatePart

type DatePart int

const (
	FilterNot                   DatePart = iota // 不等于
	FilterIn                                    // 检查值是否在列表中
	FilterNotIn                                 // 不在列表中
	FilterGTE                                   // 大于或等于传递的值
	FilterGT                                    // 大于传递值
	FilterLTE                                   // 小于或等于传递值
	FilterLT                                    // 小于传递值
	FilterRange                                 // 是否介于和给定的两个值之间
	FilterIsNull                                // 是否为空
	FilterNotIsNull                             // 是否不为空
	FilterContains                              // 是否包含指定的子字符串
	FilterInsensitiveContains                   // 不区分大小写，是否包含指定的子字符串
	FilterStartsWith                            // 以值开头
	FilterInsensitiveStartsWith                 // 不区分大小写，以值开头
	FilterEndsWith                              // 以值结尾
	FilterInsensitiveEndsWith                   // 不区分大小写，以值结尾
	FilterExact                                 // 精确匹配
	FilterInsensitiveExact                      // 不区分大小写，精确匹配
	FilterRegex                                 // 正则表达式
	FilterInsensitiveRegex                      // 不区分大小写，正则表达式
	FilterSearch                                // 全文搜索
)

const (
	DatePartDate        DatePart = iota // 日期
	DatePartYear                        // 年
	DatePartISOYear                     // ISO 8601 一年中的周数
	DatePartQuarter                     // 季度
	DatePartMonth                       // 月
	DatePartWeek                        // ISO 8601 周编号 一年中的周数
	DatePartWeekDay                     // 星期几
	DatePartISOWeekDay                  // 星期几
	DatePartDay                         // 日
	DatePartTime                        // 小时：分钟：秒
	DatePartHour                        // 小时
	DatePartMinute                      // 分钟
	DatePartSecond                      // 秒
	DatePartMicrosecond                 // 微秒
)

type FilterOp

type FilterOp int