剖析与探查的方言修正(C1)和没有真库时的方言验证(C2)

为什么:剖析是全站唯一主动查业务库的地方,以前只在守卫放行和字符串片段两层上测过,从没在真库上跑过。
本机四个容器(PG 16、MySQL 8.4、MariaDB 11、Oracle Free 23)实测,旧的 IN 列表写法在 PostgreSQL 上整数子列
对文字主键直接报 operator does not exist: character varying = integer,关系一条都核对不了。

C1 方言修正:
- IN 列表的字面量按被指向列的类型族写(key_literals):父列文字写 '12',父列数字只收整数写法的值,父列是时间、
  对不上的不拼并在备注里写「两端类型不同」;子表是 CHAR(n) 时去掉补齐的尾随空格。
- 列类型改存按方言编译的完整写法(VARCHAR2(20 CHAR)、NUMBER(10, 0)、ENUM('a','b')、TIMESTAMP WITH TIME ZONE),
  编译不了退回 str()。SQLAlchemy 把 Oracle 的 VARCHAR2 反射成通用 VARCHAR(容器实测),照数据字典写成 VARCHAR2。
  ENUM / SET 另记 enum_values;Oracle 小写带引号的表和列记 quote_name;各索引(含主键)的首列记进
  index_first_columns(下一波取值观察判断能不能对大表发窗口查询)。新探查的快照哈希会变,旧运行封存的不受影响。
- catalog._type_family 认 ENUM / SET 是文字、INTERVAL 不是数字,去掉引号里的取值再认;新增 column_family
  (有 enum_values 的是文字,PostgreSQL 枚举编译出来只有类型名);is_date_column 不再把 ENUM('date') 认成日期列。
- 码值候选:ENUM / SET 不看列名直接算候选,ENUM 列定义里这次没出现的取值也写进码值(含义待填);VARCHAR2(20 CHAR)
  的长度按 20 算;CHAR 码值去尾随空格;MySQL 上写明按排序规则分组、比较(可能不分大小写)。
- 统计信息估出的行数不超过整表统计上限时再跑一次有上限的计数确认,统计过期的大表不再被当成小表做整表统计。
- 日期列的最小值、最大值只看 0001-01-02 到 9999-12-31 之间的值,零日期、占位日期、PG 的 ±infinity 不计入,
  照实写「另有 N 个无效日期未计入」,日期范围里带 invalid 个数(界面显示)。
- 新增取值观察用的方言方法 date_literal / day_trunc / sample_from,以及按日行数、时间窗口里的取值分布、块采样三类
  查询的拼法(窗口上端截在 9999-12-31 之前,不让 infinity 多出一天)。
- 说明文字不再说「抽样」:大表看的是「按存储顺序取前 N 行」;设置项「抽样键值数」改叫「核对键值数」。

C2 验证:
- tests/test_profile_dialect_golden.py:五种方言 × 全部剖析和观察查询的完整 SQL 钉在 tests/fixtures/dialect/,
  sqlglot 逐条解析、过只读守卫,再用 qualify + annotate_types 核对 IN 两边类型族一致(附旧写法的对照)。
- scripts/dialect-it.sh(不进 CI):本机起四个容器,建虚构夹具(保留字列、Oracle 小写带引号的表、CHAR 码值、
  MySQL ENUM、零日期 / infinity / 占位日期、做旧的统计信息、超上限的大表、带索引的日期列),用 AgentLab 自己的
  探查和剖析代码跑全部查询,断言零报错、结论和手算一致。四种库都通过;MariaDB 插入时自己更新行数估算,统计信息
  做不旧,照实打印。把 IN 列表改回旧写法回跑,PG 上照样报出上面那条错误。跑完删容器、留镜像。
This commit is contained in:
ThearchyHelios
2026-10-16 10:25:28 +08:00
parent 4819b21269
commit ee7b8b2f97
21 changed files with 1499 additions and 82 deletions
+35 -5
View File
@@ -1365,7 +1365,9 @@ def is_date_column(name: str, type_name: str | None) -> bool:
数据剖析(表里只有一个日期类列时提议它作业务日期)和 SQL 检查(按业务日期以外的时间列统计)共用这一个判断。
以前两边各写一套:剖析认的「唯一日期列」,SQL 检查可能认为还有别的时间列,反过来也一样,两边对不上。
"""
t = (type_name or "").upper()
t = _type_words(type_name)
if t.startswith(("ENUM", "SET")) or "INTERVAL" in t:
return False
if "DATE" in t or "TIMESTAMP" in t:
return True
if t and not any(k in t for k in _TEXT_TYPES):
@@ -1400,11 +1402,29 @@ def _name_index(tables: Mapping[str, Any]) -> dict[tuple[str, str], set[str]]:
return index
#: 类型写法里带引号的部分(ENUM('int','date') 的取值):认类型时去掉,取值里的词不能让一列变成数字或时间
_QUOTED_IN_TYPE = re.compile(r"'(?:[^']|'')*'")
def _type_words(type_name: str | None) -> str:
"""认类型用的写法:大写、去掉引号里的取值。探查存的是按方言编译的完整写法(ENUM('paid','refund')、
VARCHAR2(20 CHAR)、TIMESTAMP WITH TIME ZONE),不再是 SQLAlchemy 的通用写法。"""
return _QUOTED_IN_TYPE.sub("''", (type_name or "").upper()).strip()
def _type_family(type_name: str | None) -> str | None:
"""列类型的大类:数字、文字、时间;认不出来返回 None(不据此排除)。"""
t = (type_name or "").upper()
"""列类型的大类:数字、文字、时间;认不出来返回 None(不据此排除)。
认的是按方言编译的完整写法:MySQL 的 ENUM / SET 是文字(取值列表里的词不算),Oracle 的 INTERVAL DAY TO SECOND
是时长、不算数字(以前按子串「INT」认成了数字)。PostgreSQL 的枚举编译出来是类型名本身,只看类型认不出来,
要看列上的取值列表(column_family)。"""
t = _type_words(type_name)
if not t:
return None
if t.startswith(("ENUM", "SET")):
return "text"
if "INTERVAL" in t:
return None
if any(k in t for k in ("CHAR", "TEXT", "CLOB", "STRING", "UUID")):
return "text"
if any(k in t for k in ("INT", "NUMBER", "NUMERIC", "DECIMAL", "SERIAL", "REAL", "FLOAT", "DOUBLE")):
@@ -1414,6 +1434,16 @@ def _type_family(type_name: str | None) -> str | None:
return None
def column_family(col: Mapping[str, Any] | None) -> str | None:
"""表结构里一列的类型大类:有取值列表(探查记下的 enum_values:MySQL 的 ENUM / SET、PostgreSQL 的枚举)的是
文字,其余按类型写法认(_type_family)。"""
if not isinstance(col, Mapping):
return None
if col.get("enum_values"):
return "text"
return _type_family(col.get("type"))
def _id_stem(column: str) -> str | None:
m = _SNAKE_ID.match(column) or _CAMEL_ID.match(column)
return m.group("stem") if m else None
@@ -1469,8 +1499,8 @@ def infer_name_relations(schema_cache: Mapping[str, Any] | None, table: str, *,
pk = list(target_meta.get("primary_key") or [])
if len(pk) != 1:
continue
pk_type = next((c.get("type") for c in target_meta.get("columns") or [] if c.get("name") == pk[0]), None)
mine, theirs = _type_family(col.get("type")), _type_family(pk_type)
pk_col = next((c for c in target_meta.get("columns") or [] if c.get("name") == pk[0]), None)
mine, theirs = column_family(col), column_family(pk_col)
if mine and theirs and mine != theirs:
continue
out.append(_relation(table, [name], target, pk, "name", cardinality=_cardinality(meta, [name])))
+295 -51
View File
@@ -41,7 +41,7 @@ import re
import time
from collections.abc import Awaitable, Callable
from dataclasses import asdict, dataclass, field
from datetime import datetime, timezone
from datetime import date as _date, datetime, timezone
from decimal import Decimal
from typing import Any
@@ -99,7 +99,7 @@ _NUMBER_FIELDS: dict[str, tuple[str, float, float, bool]] = {
"table_max_queries": ("每张表最多查询数", 1, 200, True),
"table_max_s": ("每张表时长上限(秒)", 10, 600, False),
"query_timeout_s": ("单条查询时限(秒)", 1, 60, False),
"sample_size": ("抽样键值数", 10, 10_000, True),
"sample_size": ("核对键值数", 10, 10_000, True),
"max_scan_rows": ("整表统计行数上限", 0, 10_000_000, True),
}
_ENABLED_LABEL = "开启数据剖析"
@@ -241,16 +241,82 @@ def sql_literal(value: Any, kind: str | None) -> str | None:
return "'" + value.replace("'", "''") + "'"
#: 定长文字类型(CHAR(2)、NCHAR、bpchar、CHARACTER(2)):PostgreSQL、Oracle 取回的值带尾随空格补齐
_FIXED_CHAR = re.compile(r"^\s*(?:N?CHAR|BPCHAR|CHARACTER)\b(?!\s+VARYING)", re.IGNORECASE)
def is_fixed_char(type_name: str | None) -> bool:
"""定长文字列(CHAR(n)):值的尾随空格是补齐出来的,不是取值的一部分(SQL 比较时也不算)。"""
return bool(type_name) and bool(_FIXED_CHAR.match(str(type_name)))
def key_literals(values: list[Any], kind: str | None, *, parent: str | None,
child_type: str | None) -> tuple[list[str], int]:
"""从子表取回的键值 → 去父表里对的 IN 列表字面量(去重、保持顺序):(字面量, 因为两端类型不同没拼的个数)。
字面量按**被指向列**的类型族写(catalog.column_family),不是按子表取回的值:
- 父列是文字、子列是数:写成 '123'。PostgreSQL 上 varchar 列 IN (123) 直接报「operator does not exist」;
- 父列是数、子列是文字:只收整数写法的值('0012' 也照 12 写),别的('A1')计入不同类型、不拼。Oracle 上
数字列 IN ('A1') 会把字面量转成数报 ORA-01722,MySQL 会把 'A1' 转成 0 去比、对上不该对上的行;
- 父列是时间:键不核对(各家时间字面量写法不同、精度不同),全部计入不同类型;
- 父列类型认不出:照子表取回的值的类型写(sql_literal,以前的做法)。
子表是定长文字(CHAR(n))时先去掉尾随空格:PG、Oracle 取回的 'A ' 拿去和 VARCHAR 父列比就对不上,而按 CHAR 的
语义尾随空格本来就不算。不安全的值(反斜杠、「:名字」、控制字符、太长)照 sql_literal 的规矩跳过,不算类型不同。
"""
fixed = is_fixed_char(child_type)
out: list[str] = []
mismatched = 0
for value in values:
if fixed and isinstance(value, str):
value = value.rstrip(" ")
if parent == "time":
mismatched += 1
continue
if parent == "text":
if isinstance(value, bool):
continue
if isinstance(value, (int, float, Decimal)):
lit = sql_literal(value, "number")
lit = None if lit is None else "'" + lit + "'"
else:
lit = sql_literal(value, "text")
elif parent == "number":
if isinstance(value, str):
text = value.strip()
if not _INT_TEXT.fullmatch(text):
mismatched += 1
continue
lit = str(int(text))
else:
lit = sql_literal(value, "number")
else:
lit = sql_literal(value, kind)
if lit is not None:
out.append(lit)
return list(dict.fromkeys(out)), mismatched
_DIALECT_MODULES = {"sqlite": sqlite, "postgres": postgresql, "postgresql": postgresql, "mysql": mysql,
"mariadb": mysql, "oracle": oracle}
#: 日期列的最小值、最大值只看这个区间里的值(含下限、不含上限):0000-00-00(MySQL 关了严格模式写进去的零日期)、
#: 0001-01-01、9999-12-31(「没有」「永久」的占位日期)、PostgreSQL 的 -infinity / infinity 都落在区间外。区间外的
#: 值照实数出来(「有 N 个无效日期未计入」),不让一个占位日期把业务日期的范围撑成两千年。两端整天排除:带时刻的
#: 9999-12-31 23:59:59、文字存的「0001-01-01 00:00:00」也算占位
VALID_DATE_FROM = "0001-01-02"
VALID_DATE_BEFORE = "9999-12-31"
_ISO_DAY = re.compile(r"\d{4}-\d{2}-\d{2}")
class SqlDialect:
"""剖析 SQL 的方言差异:标识符怎么加引号、怎么只取前 n 行、统计信息在哪个系统视图里。只拼字符串,不连库。
"""剖析 SQL 的方言差异:标识符怎么加引号、怎么只取前 n 行、统计信息在哪个系统视图里、日期字面量和按天截断
怎么写、有没有块采样。只拼字符串,不连库。
标识符交给 SQLAlchemy 各方言的 identifier_preparer:需要时才加引号(memberTags 加、visits 不加),
MySQL 用反引号。Oracle 尤其不能一律加双引号:探查拿到的表名是 SQLAlchemy 规整过的小写,库里其实是
大写,"visits" 加了引号就成了另一张不存在的表;不加引号 Oracle 自己转大写才对得上。
大写,"visits" 加了引号就成了另一张不存在的表;不加引号 Oracle 自己转大写才对得上。反过来,库里真是小写的
对象(建表时写了 "visits")探查时记了 quote_name,这种要强制加引号、不转大写(table、column、stats_sql)。
"""
def __init__(self, kind: str | None) -> None:
@@ -262,13 +328,64 @@ class SqlDialect:
self._prep = self._dialect.identifier_preparer
self.oracle = self.kind == "oracle"
def quote(self, name: str) -> str:
return self._prep.quote(name)
def quote(self, name: str, *, force: bool = False) -> str:
"""标识符。force:探查记了 quote_name 的名字,原样加引号(Oracle 小写带引号的对象)。"""
return self._prep.quote_identifier(name) if force else self._prep.quote(name)
def table(self, meta: dict[str, Any] | None, name: str) -> str:
"""写进 FROM 的表名:探查时指定了 schema 的带上它(Oracle 只读账号名下没有对象,全靠 schema 前缀)。"""
schema = (meta or {}).get("schema")
return f"{self._prep.quote_schema(schema)}.{self.quote(name)}" if schema else self.quote(name)
quoted = self.quote(name, force=(meta or {}).get("quote_name") is True)
return f"{self._prep.quote_schema(schema)}.{quoted}" if schema else quoted
def column(self, meta: dict[str, Any] | None, name: str) -> str:
"""写进 SQL 的列名:表结构里这一列记了 quote_name 的强制加引号。"""
cols = (meta or {}).get("columns") or []
entry = next((c for c in cols if isinstance(c, dict) and c.get("name") == name), None)
return self.quote(name, force=bool(entry and entry.get("quote_name") is True))
def date_literal(self, value: Any, *, text: bool = False) -> str:
"""日期字面量(取值观察的时间窗口、日期列的有效区间用)。PostgreSQL、MySQL、Oracle 都认 DATE 'YYYY-MM-DD';
SQLite 没有日期类型,日期存成文字,写字符串。text:列是文字存的日期(VARCHAR),按字符串比——PostgreSQL 上
varchar 和 date 比较会直接报错。只收真实存在的日期(date 或 YYYY-MM-DD),别的抛 ValueError:拼进 SQL 的
只能是我们自己算出来的日子。"""
if isinstance(value, datetime):
value = value.date()
if isinstance(value, _date):
day = value.isoformat()
elif isinstance(value, str) and _ISO_DAY.fullmatch(value):
try:
day = _date.fromisoformat(value).isoformat()
except ValueError:
raise ValueError(f"不是有效的日期:{value}") from None
else:
raise ValueError(f"不是有效的日期:{value!r}")
if text or self.kind == "sqlite":
return f"'{day}'"
return f"DATE '{day}'"
def day_trunc(self, column: str) -> str:
"""时间列截到天(按日行数用)。PostgreSQL CAST(x AS DATE);MySQL DATE(x);Oracle 必须用 TRUNC(x):Oracle 的
DATE 带时分秒,CAST(ts AS DATE) 截不掉;SQLite 的日期是文字,取前 10 个字符。"""
if self.kind in ("postgres", "postgresql"):
return f"CAST({column} AS DATE)"
if self.kind in ("mysql", "mariadb"):
return f"DATE({column})"
if self.oracle:
return f"TRUNC({column})"
return f"substr({column}, 1, 10)"
def sample_from(self, table: str, percent: float) -> str | None:
"""块采样的 FROM:PostgreSQL TABLESAMPLE SYSTEM (p)、Oracle SAMPLE BLOCK (p),按数据块随机取约 p% 的行;
MySQL、SQLite 没有块采样,返回 None(调用方退回「按存储顺序的前 N 行」,并照实写口径)。"""
p = float(percent)
if not (0 < p < 100):
raise ValueError(f"采样比例要在 0 到 100 之间:{percent}")
if self.kind in ("postgres", "postgresql"):
return f"{table} TABLESAMPLE SYSTEM ({p:g})"
if self.oracle:
return f"{table} SAMPLE BLOCK ({p:g})"
return None
def limit(self, sql: str, n: int) -> str:
"""只取前 n 行。Oracle 11g 没有 LIMIT 也没有 FETCH FIRST,一律套一层 ROWNUM。"""
@@ -304,7 +421,8 @@ class SqlDialect:
if self.oracle:
denorm = self._dialect.denormalize_name
owner = sql_literal(denorm(schema), "text") if schema else "SYS_CONTEXT('USERENV', 'CURRENT_SCHEMA')"
table = sql_literal(denorm(name), "text")
# 小写带引号的对象(quote_name)在数据字典里就是小写,不能转成大写去找
table = sql_literal(name if (meta or {}).get("quote_name") is True else denorm(name), "text")
if not (owner and table):
return None
return f"SELECT NUM_ROWS FROM ALL_TABLES WHERE OWNER = {owner} AND TABLE_NAME = {table}"
@@ -335,8 +453,49 @@ class SqlDialect:
f"WHERE {column} IS NOT NULL GROUP BY {column} ORDER BY cnt DESC, {column}")
return self.limit(sql, n)
def min_max_sql(self, table: str, columns: list[str]) -> str:
return f"SELECT {', '.join(f'MIN({c}), MAX({c})' for c in columns)} FROM {table}"
def min_max_sql(self, table: str, columns: list[tuple[str, bool]]) -> str:
"""日期列的最小值、最大值和无效日期的个数:每列三个值(MIN、MAX、区间外的个数)。columns 是 (写进 SQL 的列,
是不是文字存的日期)。只看有效区间(VALID_DATE_FROM ≤ x < VALID_DATE_BEFORE)里的值,见 VALID_DATE_FROM。
整表统计,只对小表用。"""
parts = []
for c, text in columns:
lo = self.date_literal(VALID_DATE_FROM, text=text)
hi = self.date_literal(VALID_DATE_BEFORE, text=text)
valid = f"{c} >= {lo} AND {c} < {hi}"
parts.append(f"MIN(CASE WHEN {valid} THEN {c} END), MAX(CASE WHEN {valid} THEN {c} END), "
f"SUM(CASE WHEN {c} < {lo} OR {c} >= {hi} THEN 1 ELSE 0 END)")
return f"SELECT {', '.join(parts)} FROM {table}"
# ---- 取值观察(下一轮第 3 波用):窗口、按日行数、块采样。这里先把各方言的写法定下来,金样和容器集成测试都覆盖
def _window(self, column: str, since: Any, text: bool) -> str:
"""时间窗口的条件:since 起(含),并且早于占位日期 9999-12-31——PostgreSQL 的 infinity、Oracle 的 9999-12-31
都大于任何一天,不截掉上端就会在「最近 35 天」里多出一天。"""
return (f"{column} >= {self.date_literal(since, text=text)} "
f"AND {column} < {self.date_literal(VALID_DATE_BEFORE, text=text)}")
def day_volume_sql(self, table: str, column: str, since: Any, *, text: bool = False) -> str:
"""最近若干天按天计数:since 起(含)每天几行。只在日期列打头有索引时对大表发(走索引的范围扫描)。"""
day = self.day_trunc(column)
return (f"SELECT {day} AS d, COUNT(*) AS n FROM {table} "
f"WHERE {self._window(column, since, text)} GROUP BY {day} ORDER BY d")
def window_value_counts_sql(self, table: str, column: str, date_column: str, since: Any, n: int, *,
text: bool = False) -> str:
"""时间窗口里的取值分布:业务日期 since 起(含)的行里,出现最多的 n 个取值和各自的行数。"""
sql = (f"SELECT {column}, COUNT(*) AS cnt FROM {table} "
f"WHERE {self._window(date_column, since, text)} AND {column} IS NOT NULL "
f"GROUP BY {column} ORDER BY cnt DESC, {column}")
return self.limit(sql, n)
def sample_value_counts_sql(self, table: str, column: str, percent: float, n: int) -> str | None:
"""块采样里的取值分布;没有块采样的方言返回 None。"""
source = self.sample_from(table, percent)
if source is None:
return None
sql = (f"SELECT {column}, COUNT(*) AS cnt FROM {source} WHERE {column} IS NOT NULL "
f"GROUP BY {column} ORDER BY cnt DESC, {column}")
return self.limit(sql, n)
# ==========================================================================
@@ -581,8 +740,10 @@ async def estimate_size(run: Callable[..., Awaitable[QueryResult]], dialect: Sql
"""先读统计信息;读不到(SQLite、没分析过的表)再数到 max_scan_rows + 1 行为止。
统计信息为 0 或负数(PostgreSQL 没分析过的表是 -1,MySQL 的估算值可能是 0)当作不知道:一张其实很大的表
要是被当成空表,后面就会对它做整表统计。返回 (行数, 途中没查成的几条)。这张表的查询次数、时长用完(或者任务止损)
时抛 _Stop。
要是被当成空表,后面就会对它做整表统计。统计信息说的行数不超过 max_scan_rows 时也再数一次(多一条有上限的
计数):统计信息可能是很久以前的(表后来涨到了几千万行,ANALYZE 没再跑过),照它把大表当小表,就会对它做
整表的 COUNT(DISTINCT)、MIN/MAX。数过的结果是准数(count),数到上限还没数完就按大表算(at_least)。
返回 (行数, 途中没查成的几条)。这张表的查询次数、时长用完(或者任务止损)时抛 _Stop。
"""
skips: list[_Skip] = []
sql = dialect.stats_sql(meta, name)
@@ -592,7 +753,9 @@ async def estimate_size(run: Callable[..., Awaitable[QueryResult]], dialect: Sql
except _Skip as e:
skips.append(e)
else:
if rows is not None and rows > 0:
if rows is not None and rows > max(max_scan_rows, 0):
return TableSize(rows, "stats"), skips
if rows is not None and rows > 0 and max_scan_rows <= 0:
return TableSize(rows, "stats"), skips
if max_scan_rows <= 0:
return TableSize(None, "unknown"), skips
@@ -752,6 +915,8 @@ class _CodesOutcome:
rows: int
note: str
complete: bool = False
#: 列定义(ENUM)列出的取值:这次没出现的也写进码值(含义待填),码值是「可能的取值」
declared: list[str] = field(default_factory=list)
@dataclass
@@ -901,6 +1066,11 @@ def _column(meta: dict[str, Any], name: str) -> str | None:
if isinstance(c, dict) and str(c.get("name", "")).lower() == lowered), None)
def _column_meta(meta: dict[str, Any], name: str) -> dict[str, Any] | None:
"""表结构里这一列(类型、取值列表、quote_name);name 是表结构里的写法(_column 的返回值)。"""
return next((c for c in meta.get("columns") or [] if isinstance(c, dict) and c.get("name") == name), None)
def _constraint(meta: dict[str, Any], column: str) -> str | None:
"""这一列单独是主键或某个唯一约束时返回「主键」/「唯一约束」,否则 None。"""
wanted = [column.lower()]
@@ -950,7 +1120,7 @@ async def _unique(cx: _TableCx, table: str, meta: dict[str, Any], column: str,
if not size.within(cx.settings.max_scan_rows):
return None, "too_large"
d = cx.dialect
res = await cx.run(d.unique_check_sql(d.table(meta, table), d.quote(column)))
res = await cx.run(d.unique_check_sql(d.table(meta, table), d.column(meta, column)))
row = res.rows[0] if res.rows else [None, None]
total, distinct = _as_int(row[0]), _as_int(row[1])
if total is None or distinct is None:
@@ -969,20 +1139,38 @@ def _fk_note(child: tuple[bool | None, str]) -> str:
return f"{catalog.PROFILE_NOTE_PREFIX}外键约束已保证引用完整,未抽样核对覆盖率;子表一侧{basis}:{shape}"
#: MySQL 上比较文字按列的排序规则:常见的排序规则不分大小写(_ci),PAD SPACE 的还忽略尾随空格。覆盖率、唯一性、
#: 码值的分组都按它算,写进说明,人才知道「A01」和「a01」在这里算同一个值
MYSQL_COLLATION_NOTE = "MySQL 按列的排序规则比较文字(常见的排序规则不分大小写),覆盖率和唯一性按它计算"
MYSQL_CODES_COLLATION_NOTE = "MySQL 按列的排序规则分组(常见的排序规则不分大小写),大小写不同的写法可能并成一个取值"
def _collation_note(dialect: SqlDialect, family: str | None, note: str) -> str | None:
"""MySQL、MariaDB 上文字列(或类型认不出的列)的排序规则说明;别的方言、数字列没有。"""
return note if dialect.kind in ("mysql", "mariadb") and family in ("text", None) else None
def _relation_note(*, sample: int, matched: int, coverage: float, scan_cap: int | None,
skipped_values: int, parent: tuple[bool | None, str], child: tuple[bool | None, str] | None,
holds: bool) -> str:
"""关系的剖析备注:抽样规模、覆盖率、父键和子键唯一的依据。人据此判断这条结论有多可靠。
不写日期:什么时候剖析的看这一项的 updated_at(界面按本地时间显示)。"""
holds: bool, mismatched: int = 0, collation: str | None = None) -> str:
"""关系的剖析备注:取了多少个键值、看了多少行、覆盖率、父键和子键唯一的依据。人据此判断这条结论有多可靠。
不写日期:什么时候剖析的看这一项的 updated_at(界面按本地时间显示)。
不说「抽样」:DISTINCT … LIMIT 取的是数据库先给出的那几个值,大表上是按存储顺序的前若干行里的值,不是随机抽的
(多半是最老的数据)。mismatched:和被指向列类型不同、没拼进核对的键值个数(key_literals)。"""
parts: list[str] = []
low = coverage < catalog.PROFILE_VERIFY_COVERAGE
if low:
parts.append(f"抽样覆盖率 {_percent(coverage)},可能不是这条关系")
scope = f"(只看前 {scan_cap} 行)" if scan_cap else ""
sampled = f"子表抽样 {sample} 个不同键值{scope},父表对上 {matched} 个"
parts.append(f"覆盖率 {_percent(coverage)},可能不是这条关系")
scope = f"(按存储顺序只看前 {scan_cap} 行)" if scan_cap else ""
sampled = f"子表取了 {sample} 个不同键值{scope},父表对上 {matched} 个"
parts.append(sampled if low else f"{sampled},覆盖率 {_percent(coverage)}")
if skipped_values:
parts.append(f"另有 {skipped_values} 个键值的类型不支持核对,未计入")
if mismatched:
parts.append(f"另有 {mismatched} 个键值和被指向列的类型不同(两端类型不同),未计入")
if collation:
parts.append(collation)
unique, how = parent
if unique is True:
parts.append(f"被指向列是{how}" if how in ("主键", "唯一约束") else "被指向列经计数核对唯一")
@@ -1029,18 +1217,25 @@ async def _check_relation(cx: _TableCx, table: str, rel: dict[str, Any], out: _T
size = await cx.size_with_data(table, result)
scan_cap = cx.scan_cap(size)
child_table, parent_table = d.table(meta, table), d.table(pmeta, parent)
res = await cx.run(d.distinct_sample_sql(child_table, d.quote(col), s.sample_size, scan_cap=scan_cap),
res = await cx.run(d.distinct_sample_sql(child_table, d.column(meta, col), s.sample_size, scan_cap=scan_cap),
max_rows=s.sample_size)
kind = (res.column_types or {}).get(res.columns[0]) if res.columns else None
values = [row[0] for row in res.rows if row]
literals = list(dict.fromkeys(lit for v in values if (lit := sql_literal(v, kind)) is not None))
child_col, parent_col = _column_meta(meta, col), _column_meta(pmeta, pcol)
parent_family = catalog.column_family(parent_col)
literals, mismatched = key_literals(values, kind, parent=parent_family,
child_type=(child_col or {}).get("type"))
if not values:
raise _Skip("no_data", f"{table}.{col} 没有非空值,无法核对")
if not literals and mismatched:
their = {"number": "数字", "text": "文字", "time": "日期时间"}.get(parent_family or "", "其他类型")
raise _Skip("unsupported", f"两端类型不同:{parent}.{pcol} 是{their},{table}.{col} 取到的值对不上这种类型,"
"无法核对")
if not literals:
raise _Skip("unsupported", f"{table}.{col} 的取值类型不支持核对(只核对整数和文字)")
matched = 0
for start in range(0, len(literals), IN_CHUNK):
sql = d.match_count_sql(parent_table, d.quote(pcol), literals[start:start + IN_CHUNK])
sql = d.match_count_sql(parent_table, d.column(pmeta, pcol), literals[start:start + IN_CHUNK])
matched += _as_int(_first(await cx.run(sql))) or 0
matched = min(matched, len(literals))
coverage = round(matched / len(literals), 4)
@@ -1051,9 +1246,11 @@ async def _check_relation(cx: _TableCx, table: str, rel: dict[str, Any], out: _T
if child_unique is not None:
cardinality = "one_to_one" if child_unique[0] is True else "many_to_one"
holds = coverage >= catalog.PROFILE_VERIFY_COVERAGE and cardinality is not None
unsafe = len(values) - mismatched - len(literals)
note = _relation_note(sample=len(literals), matched=matched, coverage=coverage, scan_cap=scan_cap,
skipped_values=len(values) - len(literals), parent=parent_unique, child=child_unique,
holds=holds)
skipped_values=max(unsafe, 0), parent=parent_unique, child=child_unique, holds=holds,
mismatched=mismatched,
collation=_collation_note(d, parent_family, MYSQL_COLLATION_NOTE))
checked = child_unique is not None and child_unique[0] is not None
out.relations.append(_RelationOutcome(rid=str(rel["id"]), target=_relation_target(rel), coverage=coverage,
cardinality=cardinality, holds=holds, sample=len(literals),
@@ -1076,17 +1273,27 @@ _NOT_CODE_TAILS = frozenset({"id", "no", "num", "number", "name", "desc", "descr
"at", "date", "time", "on", "amount", "price", "count", "qty", "rate", "url"})
#: 像日期的取值:2026-07-01、2026/07/01,后面可以跟时间
_DATE_TEXT = re.compile(r"^\d{4}[-/]\d{2}[-/]\d{2}")
#: 日期列最小值、最大值不计入的值(见 VALID_DATE_FROM)在说明里的说法
INVALID_DATES = "零日期 0000-00-00、0001-01-01、9999-12-31 这类占位日期或无穷大"
def _code_type_ok(type_name: str | None) -> bool:
"""整数,或者短文字(定长不超过 MAX_CODE_LEN;SQLite 的 TEXT 不带长度,也算)。"""
t = (type_name or "").upper()
def _is_enum(type_name: str | None, enum_values: Any = None) -> bool:
"""取值列表有限的列:MySQL 的 ENUM / SET(类型写法以它们开头),或者探查记了取值列表(PostgreSQL 的枚举)。"""
return bool(enum_values) or catalog._type_words(type_name).startswith(("ENUM", "SET"))
def _code_type_ok(type_name: str | None, enum_values: Any = None) -> bool:
"""ENUM / SET(取值列表有限,直接算码值候选)、整数,或者短文字(定长不超过 MAX_CODE_LEN;SQLite 的 TEXT 不带
长度,也算)。类型是按方言编译的完整写法:VARCHAR2(20 CHAR) 的长度按 20 算。"""
if _is_enum(type_name, enum_values):
return True
t = catalog._type_words(type_name)
if not t or any(k in t for k in ("CLOB", "BLOB", "BINARY", "JSON", "DATE", "TIME", "INTERVAL", "REAL", "FLOAT",
"DOUBLE", "BOOL")):
return False
if "INT" in t:
return True
size = re.search(r"\(\s*(\d+)\s*(?:,\s*(\d+)\s*)?\)", t)
size = re.search(r"\(\s*(\d+)(?:\s+(?:CHAR|BYTE))?\s*(?:,\s*(\d+)\s*)?\)", t)
if any(k in t for k in ("NUMBER", "NUMERIC", "DECIMAL")):
return size is None or not size.group(2) or int(size.group(2)) == 0
if any(k in t for k in ("CHAR", "TEXT", "STRING")):
@@ -1100,9 +1307,9 @@ def _looks_like_code(name: str) -> bool:
def _code_columns(meta: dict[str, Any], notes: dict[str, Any]) -> list[str]:
"""要取值分布的列:目录里度量类型记为状态的、剖析以前提过码值候选的(再核一次)、或者类型和命名像状态、
类型、渠道的整数或短文字列。主键、唯一约束列、关系里的键列不算;码值人工确认或驳回过的不再取。
被遮罩的列也列出来,由检查记为「被遮罩」跳过——要让人看得见为什么它没有码值。"""
"""要取值分布的列:目录里度量类型记为状态的、剖析以前提过码值候选的(再核一次)、ENUM / SET 列(取值列表有限,
不看名字)、或者类型和命名像状态、类型、渠道的整数或短文字列。主键、唯一约束列、关系里的键列不算;码值人工确认
或驳回过的不再取。被遮罩的列也列出来,由检查记为「被遮罩」跳过——要让人看得见为什么它没有码值。"""
pk = [c.lower() for c in meta.get("primary_key") or []]
unique = {str(g[0]).lower() for g in meta.get("unique") or [] if isinstance(g, list) and len(g) == 1}
keys = {str(c).lower() for r in notes.get("relations") or [] if isinstance(r, dict) for c in r.get("columns") or []}
@@ -1117,23 +1324,28 @@ def _code_columns(meta: dict[str, Any], notes: dict[str, Any]) -> list[str]:
status_measure = (isinstance(measure, dict) and measure.get("value") == "status"
and measure.get("status") != "rejected")
profiled = isinstance(codes, dict) and codes.get("source") == "profile"
if not (status_measure or profiled or _looks_like_code(name)):
enum = _is_enum(col.get("type"), col.get("enum_values"))
if not (status_measure or profiled or enum or _looks_like_code(name)):
continue
lowered = name.lower()
if (pk == [lowered]) or lowered in unique or lowered in keys or not _code_type_ok(col.get("type")):
if (pk == [lowered]) or lowered in unique or lowered in keys or not _code_type_ok(col.get("type"),
col.get("enum_values")):
continue
out.append(name)
return out
def _code_key(value: Any) -> str | None:
"""取值分布里的一个取值 → 码值(文字)。只认整数和不太长的文字。"""
def _code_key(value: Any, *, fixed: bool = False) -> str | None:
"""取值分布里的一个取值 → 码值(文字)。只认整数和不太长的文字。fixed:定长文字列(CHAR(n)),去掉补齐的尾随
空格(PG、Oracle 取回的是 'A ',WHERE status = 'A' 照样对得上,码值写 'A')。"""
if value is None or isinstance(value, bool):
return None
if isinstance(value, int):
return str(value)
if isinstance(value, float):
return str(int(value)) if value.is_integer() else None
if isinstance(value, str) and fixed:
value = value.rstrip(" ")
if isinstance(value, str) and value.strip() and len(value) <= MAX_CODE_LEN and not _CONTROL.search(value):
return value
return None
@@ -1151,29 +1363,48 @@ async def _check_codes(cx: _TableCx, table: str, column: str, out: _TableOutcome
if cx.is_masked(column):
raise _Skip("masked", f"{table}.{column} 在数据源设置中被遮罩,不取值", carry=False)
d, meta = cx.dialect, cx.tables[table]
col_meta = _column_meta(meta, column) or {}
size = await cx.size_with_data(table, result)
scan_cap = cx.scan_cap(size)
res = await cx.run(d.value_counts_sql(d.table(meta, table), d.quote(column), CODES_MAX + 1, scan_cap=scan_cap),
res = await cx.run(d.value_counts_sql(d.table(meta, table), d.column(meta, column), CODES_MAX + 1,
scan_cap=scan_cap),
max_rows=CODES_MAX + 1)
if not res.rows:
raise _Skip("no_data", f"{table}.{column} 没有非空值,无法取值分布")
if len(res.rows) > CODES_MAX:
raise _Skip("high_cardinality", f"{table}.{column} 的取值超过 {CODES_MAX} 个,不作为码值候选", carry=False)
values: list[tuple[str, int]] = []
fixed = is_fixed_char(col_meta.get("type"))
enum = _is_enum(col_meta.get("type"), col_meta.get("enum_values"))
counts: dict[str, int] = {}
for row in res.rows:
key = _code_key(row[0])
key = _code_key(row[0], fixed=fixed)
if key is None:
raise _Skip("unsupported", f"{table}.{column} 的取值不是整数或短文字,不作为码值候选", carry=False)
values.append((key, _as_int(row[1]) or 0))
if len(values) >= 3 and all(n == 1 for _, n in values):
# 每个取值只出现一次(票种编码 T01…T09):这是一列标识,不是状态码
counts[key] = counts.get(key, 0) + (_as_int(row[1]) or 0)
values = list(counts.items())
if len(values) >= 3 and all(n == 1 for _, n in values) and not enum:
# 每个取值只出现一次(票种编码 T01…T09):这是一列标识,不是状态码。ENUM 的取值列表是列定义给的,不按这条判
raise _Skip("high_cardinality", f"{table}.{column} 的取值各不相同,像标识而不是码值,不作为码值候选",
carry=False)
rows = sum(n for _, n in values)
scope = f"按前 {scan_cap} 行统计" if scan_cap else "统计全表"
# 不说「抽样」:大表看的是按存储顺序的前若干行(多半是最老的数据),不是随机抽的
scope = f"按存储顺序取前 {scan_cap} 行统计" if scan_cap else "统计全表"
spread = "、".join(f"{k}({_share(n, rows)})" for k, n in values)
note = f"{NOTE_PREFIX}{scope},{rows} 行非空值共 {len(values)} 个取值:{spread}。"
out.codes.append(_CodesOutcome(column=column, values=values, rows=rows, note=note, complete=scan_cap is None))
extra: list[str] = []
# ENUM 的取值列表(SET 的是成员,取值是成员的组合,不算):这次没出现的也是可能的取值
is_set = catalog._type_words(col_meta.get("type")).startswith("SET")
declared = [] if is_set else [str(v) for v in col_meta.get("enum_values") or []]
unseen = [v for v in declared if v not in counts]
if unseen:
extra.append(f"列定义里另有 {len(unseen)} 个取值这次没有出现:{'、'.join(unseen[:CODES_MAX])}")
family = "text" if enum else catalog.column_family(col_meta)
collation = _collation_note(d, family, MYSQL_CODES_COLLATION_NOTE)
if collation:
extra.append(collation)
tail = "".join(f";{x}" for x in extra)
note = f"{NOTE_PREFIX}{scope},{rows} 行非空值共 {len(values)} 个取值:{spread}{tail}。"
out.codes.append(_CodesOutcome(column=column, values=values, rows=rows, note=note, complete=scan_cap is None,
declared=unseen))
def _is_date_column(col: dict[str, Any]) -> bool:
@@ -1190,20 +1421,31 @@ async def _check_dates(cx: _TableCx, table: str, columns: list[str], total: int,
if not size.within(cx.settings.max_scan_rows):
raise _Skip("too_large", f"{table} 的行数超过整表统计的行数上限({cx.settings.max_scan_rows} 行),"
"不取日期列的最小值和最大值")
res = await cx.run(d.min_max_sql(d.table(meta, table), [d.quote(c) for c in columns]))
# 文字存的日期(SQLite 的 TEXT、业务库里的 VARCHAR 日期)按字符串和有效区间比;日期类型的按日期字面量比
texts = [catalog.column_family(_column_meta(meta, c)) != "time" for c in columns]
res = await cx.run(d.min_max_sql(d.table(meta, table), [(d.column(meta, c), t) for c, t in zip(columns, texts)]))
row = res.rows[0] if res.rows else []
invalid: dict[str, int] = {}
for i, column in enumerate(columns):
low, high = (row[2 * i], row[2 * i + 1]) if len(row) >= 2 * i + 2 else (None, None)
low, high, bad = (row[3 * i], row[3 * i + 1], row[3 * i + 2]) if len(row) >= 3 * i + 3 else (None, None, 0)
invalid[column] = _as_int(bad) or 0
if low is None or high is None or not (_DATE_TEXT.match(str(low)) and _DATE_TEXT.match(str(high))):
continue
result.date_ranges.append({"column": column, "min": str(low), "max": str(high)})
found: dict[str, Any] = {"column": column, "min": str(low), "max": str(high)}
if invalid[column]:
found["invalid"] = invalid[column]
result.date_ranges.append(found)
if total != 1:
return
if not result.date_ranges:
if invalid.get(columns[0]):
raise _Skip("no_data", f"{table}.{columns[0]} 只有 {invalid[columns[0]]} 个无效日期({INVALID_DATES}),"
"没有可识别的日期值")
raise _Skip("no_data", f"{table}.{columns[0]} 没有可识别的日期值")
found = result.date_ranges[0]
dropped = (f"另有 {found['invalid']} 个无效日期({INVALID_DATES})未计入," if found.get("invalid") else "")
note = (f"{NOTE_PREFIX}表里只有这一个日期类列,取值从 {str(found['min'])[:19]} 到 "
f"{str(found['max'])[:19]},可作为业务日期的参考。")
f"{str(found['max'])[:19]},{dropped}可作为业务日期的参考。")
out.business_date = _DateOutcome(column=found["column"], low=found["min"], high=found["max"], note=note)
@@ -1241,6 +1483,8 @@ def _codes_value(c: _CodesOutcome, item: dict[str, Any] | None) -> dict[str, str
沿用它的含义;它写了、数据里没出现的取值也留着——码值是「可能的取值」,没出现不等于不存在。"""
old = item.get("value") if isinstance(item, dict) and isinstance(item.get("value"), dict) else {}
value = {key: str(old.get(key) or "") for key, _ in c.values}
for key in c.declared:
value.setdefault(key, str(old.get(key) or ""))
for key, meaning in old.items():
if key not in value and isinstance(meaning, str) and meaning.strip():
value[key] = meaning
@@ -1744,8 +1988,8 @@ def ensure_enabled(row: Any, settings: ProfileSettings | None = None) -> Profile
#: 有效行过滤核对的说法(写进这一项的 note;前面是模型给的依据)
FILTER_CHECKED = "剖析核对:排除 {share} 的行(共 {rows} 行)"
FILTER_SAMPLED = "剖析核对:按前 {rows} 行统计,排除 {share} 的行"
FILTER_SAMPLED_EDGE = "剖析核对:按前 {rows} 行统计,{what},请人工核对"
FILTER_SAMPLED = "剖析核对:按存储顺序取前 {rows} 行统计,排除 {share} 的行"
FILTER_SAMPLED_EDGE = "剖析核对:按存储顺序取前 {rows} 行统计,{what},请人工核对"
FILTER_UNCHECKED = "没有核对排除比例({why})"
FILTER_NOT_ENABLED = "数据源没有开数据剖析"
+77 -9
View File
@@ -165,6 +165,74 @@ def _unique_groups(constraints: list[dict[str, Any]], indexes: list[dict[str, An
return groups
def type_text(col_type: Any, dialect: Any) -> str:
"""反射到的列类型 → 存进表结构的写法:按这个数据源的方言编译的完整写法(VARCHAR2(20 CHAR)、NUMBER(10, 0)、
ENUM('paid','refund')、TIMESTAMP WITH TIME ZONE),编译不了的退回 str()。
以前存的是 str(类型),即 SQLAlchemy 的通用写法:Oracle 的 VARCHAR2、NUMBER 丢了长度和精度,MySQL 的 ENUM 丢了
取值列表,PostgreSQL 的 TIMESTAMP 丢了时区。类型写不全,表结构前后比对就看不出类型变了,ENUM 状态列也进不了
码值候选。这一改会让新探查的表结构快照哈希变化(提示词里的类型写法变长),旧运行封存的快照不受影响。"""
if col_type is None:
return ""
try:
compiled = str(col_type.compile(dialect=dialect))
except Exception: # noqa: BLE001 - 编译不了(NullType 等)就用通用写法,不让一列拖垮整次探查
return str(col_type)
if getattr(dialect, "name", "") == "oracle" and compiled.startswith("VARCHAR("):
# SQLAlchemy 把 Oracle 的 VARCHAR2 反射成通用的 VARCHAR,按 Oracle 方言编译出来是 VARCHAR(10 CHAR)(容器集成
# 测试实测)。Oracle 的数据字典里只有 VARCHAR2(建表写 VARCHAR 也存成 VARCHAR2),照数据字典写
compiled = "VARCHAR2" + compiled[len("VARCHAR"):]
return compiled
def _enum_values(col_type: Any) -> list[str] | None:
"""ENUM(MySQL、PostgreSQL 的枚举,都是 sqltypes.Enum 的子类)的取值列表,MySQL SET 的成员列表;别的类型 None。"""
from sqlalchemy.dialects.mysql import SET
from sqlalchemy.types import Enum
if isinstance(col_type, Enum):
values = list(col_type.enums or [])
elif isinstance(col_type, SET):
values = list(col_type.values or [])
else:
return None
return [str(v) for v in values]
def _forced_quote(name: Any) -> bool:
"""名字必须原样加引号:Oracle 反射回来的全小写对象(建表时写了 "visits")是 quoted_name(quote=True)。
它存进 JSON 就成了普通字符串,剖析拼 SQL 时不加引号,Oracle 把它转成大写 VISITS,查的是另一个不存在的对象。"""
return getattr(name, "quote", None) is True
def column_entry(col: Mapping[str, Any], dialect: Any) -> dict[str, Any]:
"""反射到的一列 → 表结构里的一列:名字、按方言编译的类型、可空、注释;ENUM / SET 另记取值列表(enum_values),
要强制加引号的名字另记 quote_name。只在有的时候写这两个键:其余列和以前一字不差。"""
entry: dict[str, Any] = {
"name": str(col["name"]),
"type": type_text(col.get("type"), dialect),
"nullable": bool(col.get("nullable", True)),
"comment": col.get("comment") or None,
}
values = _enum_values(col.get("type"))
if values:
entry["enum_values"] = values
if _forced_quote(col.get("name")):
entry["quote_name"] = True
return entry
def index_first_columns(indexes: list[dict[str, Any]], pk: list[str]) -> list[str]:
"""哪些列打头有索引:各索引(含主键)的第一列,去重、按名字排序。取值观察看大表的最新业务日期、按日行数时,
只在业务日期列打头有索引时才发窗口查询(按它走索引,不扫全表)。表达式索引(列名是 None)不算。"""
first = {str(pk[0])} if pk else set()
for ix in indexes:
cols = ix.get("column_names") or []
if cols and cols[0] is not None:
first.add(str(cols[0]))
return sorted(first)
async def introspect(source: Any, *, schema: str | None = None) -> dict[str, Any]:
"""探查整个库的结构,结果直接存进 DataSource.schema_cache。
@@ -266,24 +334,20 @@ async def introspect(source: Any, *, schema: str | None = None) -> dict[str, Any
# 只读账号名下没有这些对象,全靠跨 schema 授权
"qualified": f"{target_schema}.{name}" if target_schema else name,
"schema": target_schema,
"columns": [
{
"name": c["name"],
"type": str(c.get("type") or ""),
"nullable": bool(c.get("nullable", True)),
"comment": c.get("comment") or None,
}
for c in columns
],
"columns": [column_entry(c, sync_conn.dialect) for c in columns],
"primary_key": pk,
"comment": comment,
"is_view": name in views,
}
if _forced_quote(name):
tables[name]["quote_name"] = True
if name in fk_ok:
tables[name]["foreign_keys"] = _foreign_keys(fk_by.get(key) or [], target_schema, default_schema)
if name in uq_ok:
tables[name]["unique"] = _unique_groups(uq_by.get(key) or [],
(ix_by.get(key) or []) if name in ix_ok else [], pk)
if name in ix_ok:
tables[name]["index_first_columns"] = index_first_columns(ix_by.get(key) or [], pk)
payload: dict[str, Any] = {"tables": tables, "truncated": truncated,
"total": len(names) + len(views)}
if failures and not tables:
@@ -471,6 +535,10 @@ def describe_table(source: Any, table: str, *, catalog: Mapping[str, Mapping[str
marks.append("非空")
if col.get("comment"):
marks.append(col["comment"])
values = col.get("enum_values")
if values and "(" not in str(col.get("type") or ""):
# PostgreSQL 的枚举类型写法只有类型名(order_status):取值列表另外写出来,模型才知道能写哪些值
marks.append("取值:" + "、".join(str(v) for v in values[:30]) + ("…" if len(values) > 30 else ""))
suffix = f" {'、'.join(marks)}" if marks else ""
lines.append(f" {col['name']} {col['type']}{suffix}")
if catalog: