API 参考¶

sqlite_utils.db.Database ¶

class sqlite_utils.db.Database(filename_or_conn=None, memory=False, memory_name=None, recreate=False, recursive_triggers=True, tracer=None, use_counts_table=False, execute_plugins=True, strict=False)[source]¶

SQLite 数据库连接的封装，添加了各种有用的实用方法。

创建一个实例

# create data.db file, or open existing:
db = Database("data.db")
# Create an in-memory database:
dB = Database(memory=True)

参数：

filename_or_conn (str | Path | Connection | None) – 文件路径字符串、pathlib.Path 对象或 sqlite3 连接
memory (bool) – 设置为 True 创建内存数据库
memory_name (str | None) – 创建一个命名内存数据库，可在多个连接间共享
recreate (bool) – 设置为 True 删除并重新创建文件数据库 (危险)
recursive_triggers (bool) – 默认为 True，启用 PRAGMA recursive_triggers=on; - 设置为 False 以避免设置此 pragma
tracer (Callable | None) – 设置一个跟踪函数 (print 可用)，每次执行 SQL 查询时将以 sql, parameters 为参数调用它
use_counts_table (bool) – 设置为 True 使用缓存的计数表（如果可用）。参见使用触发器缓存表计数
strict (bool) – 对所有创建的表应用 STRICT 模式（除非覆盖）
execute_plugins (bool)

close()[source]¶: 关闭 SQLite 连接和底层数据库文件

ensure_autocommit_off()[source]¶

确保此数据库连接的自动提交已关闭。

示例用法

with db.ensure_autocommit_off():
    # do stuff here

这将在代码块结束时重置为之前的自动提交状态。

tracer(tracer=None)[source]¶

上下文管理器，用于临时设置跟踪函数 - 所有执行的 SQL 查询都将传递给它。

跟踪函数应接受两个参数：sql 和 parameters

示例用法

with db.tracer(print):
    db["creatures"].insert({"name": "Cleo"})

参见跟踪查询。

参数：: tracer (Callable | None) – 接受 sql 和 parameters 参数的可调用对象

__getitem__(table_name)[source]¶

db[table_name] 返回指定名称表的 Table 对象。如果表尚不存在，将在第一次插入数据时创建它。

参数：: table_name (str) – 表的名称
返回类型：: Table | View

register_function(fn=None, deterministic=False, replace=False, name=None)[source]¶

fn 将作为 SQL 中的函数可用，具有相同的名称和参数数量。可用作装饰器

@db.register_function
def upper(value):
    return str(value).upper()

装饰器可以接受参数

@db.register_function(deterministic=True, replace=True)
def upper(value):
    return str(value).upper()

参见注册自定义 SQL 函数。

参数：

fn (Callable | None) – 要注册的函数
deterministic (bool) – 对于给定输入始终返回相同输出的函数，设置为 True
replace (bool) – 设置为 True 替换具有相同名称的现有函数 - 否则抛出错误
name (str | None) – SQLite 函数的名称 - 如果未指定，将使用 Python 函数的名称

register_fts4_bm25()[source]¶: 注册 rank_bm25(match_info) 函数，用于计算 SQLite FTS4 的相关性。

attach(alias, filepath)[source]¶

将另一个 SQLite 数据库文件以指定的别名附加到此连接，相当于

ATTACH DATABASE 'filepath.db' AS alias

参数：

alias (str) – 要使用的别名
filepath (str | Path) – 磁盘上的 SQLite 数据库文件路径

query(sql, params=None)[source]¶

执行 sql 并返回一个迭代器，其中包含表示每一行的字典。

参数：

sql (str) – 要执行的 SQL 查询
params (Iterable | dict | None) – 该查询要使用的参数 - 对于 where id = ? 参数使用迭代器，对于 where id = :id 使用字典

返回类型：

Generator[dict, None, None]

execute(sql, parameters=None)[source]¶

执行 SQL 查询并返回 sqlite3.Cursor。

参数：

sql (str) – 要执行的 SQL 查询
parameters (Iterable | dict | None) – 该查询要使用的参数 - 对于 where id = ? 参数使用迭代器，对于 where id = :id 使用字典

返回类型：

Cursor

executescript(sql)[source]¶

执行由 ; 分隔的多条 SQL 语句，并返回 sqlite3.Cursor。

参数：: sql (str) – 要执行的 SQL
返回类型：: Cursor

table(table_name, **kwargs)[source]¶

返回一个表对象，可选择配置默认选项。

有关选项详情，请参见 sqlite_utils.db.Table。

参数：: table_name (str) – 表的名称
返回类型：: Table | View

quote(value)[source]¶

对值应用 SQLite 字符串引用，包括将其用单引号括起来。

参数：: value (str) – 要引用的字符串
返回类型：: str

quote_fts(query)[source]¶

转义 SQLite 全文搜索查询中的特殊字符。

这是通过在查询中的每个标记周围加上双引号来实现的，以避免 NOT 和 OR 等词语具有此处定义的 FTS 查询语法中的特殊含义

https://www.sqlite.org/fts5.html#full_text_query_syntax

如果查询包含不匹配的 " 字符，则在末尾添加一个。

参数：: query (str) – 要转义的字符串
返回类型：: str

quote_default_value(value)[source]¶

参数：: value (str)
返回类型：: str

table_names(fts4=False, fts5=False)[source]¶

此数据库中的字符串表名列表。

参数：

fts4 (bool) – 仅返回属于 FTS4 索引的表
fts5 (bool) – 仅返回属于 FTS5 索引的表

返回类型：

List[str]

view_names()[source]¶

此数据库中的字符串视图名列表。

返回类型：: List[str]

property tables: List[Table][source]¶: 此数据库中的 Table 对象列表。

property views: List[View][source]¶: 此数据库中的 View 对象列表。

property triggers: List[Trigger][source]¶: 此数据库中表示触发器的 (name, table_name, sql) 元组列表。

property triggers_dict: Dict[str, str][source]¶: 此数据库中触发器的 {trigger_name: sql} 字典。

property schema: str[source]¶: 此数据库的 SQL 模式。

property supports_strict: bool[source]¶: 此数据库是否支持 STRICT 模式？

property sqlite_version: Tuple[int, ...][source]¶: SQLite 版本，以整数元组表示，例如 (3, 36, 0)。

property journal_mode: str[source]¶

此数据库当前的 journal_mode。

https://www.sqlite.org/pragma.html#pragma_journal_mode

enable_wal()[source]¶: 将 journal_mode 设置为 'wal' 以启用预写日志模式（Write-Ahead Log）。

disable_wal()[source]¶: 将 journal_mode 重置回 'delete' 以禁用预写日志模式（Write-Ahead Log）。

enable_counts()[source]¶: 为此数据库中的每个表启用基于触发器的计数缓存，参见使用触发器缓存表计数。

cached_counts(tables=None)[source]¶

返回指定表的缓存计数 {table_name: count} 字典；如果未提供 tables，则返回所有表的计数。

参数：: tables (Iterable[str] | None) – 要返回计数的表子集列表。
返回类型：: Dict[str, int]

reset_counts()[source]¶: 重新计算表的缓存计数。

create_table_sql(name, columns, pk=None, foreign_keys=None, column_order=None, not_null=None, defaults=None, hash_id=None, hash_id_columns=None, extracts=None, if_not_exists=False, strict=False)[source]¶

返回用于创建指定表的 SQL CREATE TABLE 语句。

参数：

name (str) – 表名
columns (Dict[str, Any]) – 将列名映射到其类型的字典，例如 {"name": str, "age": int}
pk (Any | None) – 用作主键的列名字符串，或用于包含多个列的复合主键的字符串元组
foreign_keys (Iterable[str | ForeignKey | Tuple[str, str] | Tuple[str, str, str] | Tuple[str, str, str, str]] | List[str | ForeignKey | Tuple[str, str] | Tuple[str, str, str] | Tuple[str, str, str, str]] | None) – 此表的外键定义列表
column_order (List[str] | None) – 指定哪些列应排在前面的列表
not_null (Iterable[str] | None) – 应创建为 NOT NULL 的列列表
defaults (Dict[str, Any] | None) – 指定列默认值的字典
hash_id (str | None) – 用作主键的列名，其中包含其他列的哈希值
hash_id_columns (Iterable[str] | None) – 计算行哈希 ID 时要使用的列列表
extracts (Dict[str, str] | List[str] | None) – 插入时要提取到单独表中的列列表或字典，参见在插入/upsert 期间自动填充查找表
if_not_exists (bool) – 使用 CREATE TABLE IF NOT EXISTS
strict (bool) – 对表应用 STRICT 模式

返回类型：

str

create_table(name, columns, pk=None, foreign_keys=None, column_order=None, not_null=None, defaults=None, hash_id=None, hash_id_columns=None, extracts=None, if_not_exists=False, replace=False, ignore=False, transform=False, strict=False)[source]¶

创建指定名称和 {column_name: type} 列的表。

参见显式创建表。

参数：

name (str) – 表名
columns (Dict[str, Any]) – 将列名映射到其类型的字典，例如 {"name": str, "age": int}
pk (Any | None) – 用作主键的列名字符串，或用于包含多个列的复合主键的字符串元组
foreign_keys (Iterable[str | ForeignKey | Tuple[str, str] | Tuple[str, str, str] | Tuple[str, str, str, str]] | List[str | ForeignKey | Tuple[str, str] | Tuple[str, str, str] | Tuple[str, str, str, str]] | None) – 此表的外键定义列表
column_order (List[str] | None) – 指定哪些列应排在前面的列表
not_null (Iterable[str] | None) – 应创建为 NOT NULL 的列列表
defaults (Dict[str, Any] | None) – 指定列默认值的字典
hash_id (str | None) – 用作主键的列名，其中包含其他列的哈希值
hash_id_columns (Iterable[str] | None) – 计算行哈希 ID 时要使用的列列表
extracts (Dict[str, str] | List[str] | None) – 插入时要提取到单独表中的列列表或字典，参见在插入/upsert 期间自动填充查找表
if_not_exists (bool) – 使用 CREATE TABLE IF NOT EXISTS
replace (bool) – 如果表已存在，则删除并替换
ignore (bool) – 如果表已存在，则静默不做任何操作
transform (bool) – 如果表已存在，则将其转换为符合指定模式
strict (bool) – 对表应用 STRICT 模式

返回类型：

Table

rename_table(name, new_name)[source]¶

重命名表。

参数：

name (str) – 当前表名
new_name (str) – 重命名后的名称

create_view(name, sql, ignore=False, replace=False)[source]¶

使用指定名称创建新的 SQL 视图 - sql 应以 SELECT ... 开头。

参数：

name (str) – 视图的名称
sql (str) – 用于此视图的 SQL SELECT 查询。
ignore (bool) – 如果已存在同名视图，设置为 True 则不做任何操作
replace (bool) – 如果已存在同名视图，设置为 True 则替换该视图

m2m_table_candidates(table, other_table)[source]¶

给定两个表名，返回可能定义这两个表之间多对多关系的表的名称，判断依据是它们具有指向这两个表的外部键。

参数：

table (str) – 表名
other_table (str) – 另一个表名

返回类型：

List[str]

add_foreign_keys(foreign_keys)[source]¶

参见一次添加多个外键约束。

参数：: foreign_keys (Iterable[Tuple[str, str, str, str]]) – (table, column, other_table, other_column) 元组列表

index_foreign_keys()[source]¶: 为此数据库中每个表上的每个外键列创建索引。

vacuum()[source]¶: 对此数据库运行 SQLite VACUUM。

analyze(name=None)[source]¶

对整个数据库或指定表或索引运行 ANALYZE。

参数：: name – 对这个指定名称的表或索引运行 ANALYZE

iterdump()[source]¶

表示数据库 SQL 转储的字符串序列

返回类型：: Generator[str, None, None]

init_spatialite(path=None)[source]¶

init_spatialite 方法将加载并初始化 SpatiaLite 扩展。path 参数应是已编译扩展的绝对路径，可以使用 find_spatialite 查找该路径。

如果 SpatiaLite 成功初始化，则返回 True。

from sqlite_utils.db import Database
from sqlite_utils.utils import find_spatialite

db = Database("mydb.db")
db.init_spatialite(find_spatialite())

如果 SpatiaLite 安装在非预期位置（例如，用于测试备用版本），则可以传入绝对路径

from sqlite_utils.db import Database
from sqlite_utils.utils import find_spatialite

db = Database("mydb.db")
db.init_spatialite("./local/mod_spatialite.dylib")

参数：: path (str | None) – 磁盘上 SpatiaLite 模块的路径
返回类型：: bool

sqlite_utils.db.Queryable¶

Table 和 View 都是 Queryable 的子类，提供对以下方法的访问

class sqlite_utils.db.Queryable(db, name)[source]¶

exists()[source]¶

此表或视图是否存在？

返回类型：: bool

count_where(where=None, where_args=None)[source]¶

执行 SELECT count(*) FROM table WHERE ... 并返回计数。

参数：

where (str | None) – 要使用的 SQL where 片段，例如 id > ?
where_args (Iterable | dict | None) – 与该片段一起使用的参数 - 对于 id > ? 参数使用迭代器，对于 id > :id 使用字典

返回类型：

int

property count: int[source]¶: 此表或视图中的行计数。

property rows: Generator[dict, None, None][source]¶: 迭代此表或视图中每一行的字典。

rows_where(where=None, where_args=None, order_by=None, select='*', limit=None, offset=None)[source]¶

迭代此表或视图中符合指定 where 子句的每一行。

将每一行作为字典返回。有关更多详细信息，请参见列出行。

参数：

where (str | None) – 要使用的 SQL where 片段，例如 id > ?
where_args (Iterable | dict | None) – 与该片段一起使用的参数 - 对于 id > ? 参数使用迭代器，对于 id > :id 使用字典
order_by (str | None) – 要排序的列或 SQL 片段
select (str) – 要选择的逗号分隔列列表 - 默认为 *
limit (int | None) – 要限制的行数（整数）
offset (int | None) – SQL offset 的整数值

返回类型：

Generator[dict, None, None]

pks_and_rows_where(where=None, where_args=None, order_by=None, limit=None, offset=None)[source]¶

类似于 .rows_where() 但返回 (pk, row) 对 - pk 可以是单个值或元组。

参数：

where (str | None) – 要使用的 SQL where 片段，例如 id > ?
where_args (Iterable | dict | None) – 与该片段一起使用的参数 - 对于 id > ? 参数使用迭代器，对于 id > :id 使用字典
order_by (str | None) – 要排序的列或 SQL 片段
select – 要选择的逗号分隔列列表 - 默认为 *
limit (int | None) – 要限制的行数（整数）
offset (int | None) – SQL offset 的整数值

返回类型：

Generator[Tuple[Any, Dict], None, None]

property columns: List[Column][source]¶: 表示此表或视图中列的 Columns 列表。

property columns_dict: Dict[str, Any][source]¶: 表示此表或视图中列的 {column_name: python-type} 字典。

property schema: str[source]¶: 此表或视图的 SQL 模式。

sqlite_utils.db.Table¶

class sqlite_utils.db.Table(db, name, pk=None, foreign_keys=None, column_order=None, not_null=None, defaults=None, batch_size=100, hash_id=None, hash_id_columns=None, alter=False, ignore=False, replace=False, extracts=None, conversions=None, columns=None, strict=False)[source]¶

基类：Queryable

表通常应使用 db.table(table_name) 或 db[table_name] 方法初始化。

以下可选参数可以传递给 db.table(table_name, ...)

参数：

db (Database) – 由 db.table(table_name) 提供
name (str) – 由 db.table(table_name) 提供
pk (Any | None) – 主键列的名称，或列的元组
foreign_keys (Iterable[str | ForeignKey | Tuple[str, str] | Tuple[str, str, str] | Tuple[str, str, str, str]] | List[str | ForeignKey | Tuple[str, str] | Tuple[str, str, str] | Tuple[str, str, str, str]] | None) – 外键定义列表
column_order (List[str] | None) – 表中列名应有的顺序列表
not_null (Iterable[str] | None) – 不能为 null 的列列表
defaults (Dict[str, Any] | None) – 列名和默认值的字典
batch_size (int) – 每次插入的行数（整数）
hash_id (str | None) – 如果为 True，则使用行值的哈希作为主键
hash_id_columns (Iterable[str] | None) – 用于 hash_id 的列列表
alter (bool) – 如果为 True，则在表与模式不匹配时自动修改表
ignore (bool) – 如果为 True，则在插入时忽略已存在的行
replace (bool) – 如果为 True，则在插入时替换已存在的行
extracts (Dict[str, str] | List[str] | None) – 插入时要提取到单独表中的列名字典或列表
conversions (dict | None) – 列名和转换函数的字典
columns (Dict[str, Any] | None) – 列名到列类型的字典
strict (bool) – 如果为 True，则对表应用 STRICT 模式

last_rowid: int | None = None¶: 最后插入、更新或选择的行的 rowid。

last_pk: Any | None = None¶: 最后插入、更新或选择的行的主键。

property count: int[source]¶: 此表中的行计数 - 可选地来自表计数缓存（如果已配置）。

exists()[source]¶

此表或视图是否存在？

返回类型：: bool

property pks: List[str][source]¶: 此表的主键列。

property use_rowid: bool[source]¶: 此表是否使用 rowid 作为其主键（未指定其他主键）？

get(pk_values)[source]¶

返回指定主键的行（作为字典）。

如果找不到匹配的行，则引发 sqlite_utils.db.NotFoundError。

参数：: pk_values (list | tuple | str | int) – 单个值，或对于具有复合主键的表，使用值的元组
返回类型：: dict

property foreign_keys: List[ForeignKey][source]¶: 此表上定义的外键列表。

property virtual_table_using: str | None[source]¶: 虚拟表的类型，如果不是虚拟表则为 None。

property indexes: List[Index][source]¶: 此表上定义的索引列表。

property xindexes: List[XIndex][source]¶: 使用更详细的 XIndex 格式在此表上定义的索引列表。

property triggers: List[Trigger][source]¶: 此表上定义的触发器列表。

property triggers_dict: Dict[str, str][source]¶: 此表上定义的触发器 {trigger_name: sql} 字典。

property default_values: Dict[str, Any][source]¶: {column_name: default_value} 此表中列的默认值字典。

property strict: bool[source]¶: 这是 STRICT 表吗？

create(columns, pk=None, foreign_keys=None, column_order=None, not_null=None, defaults=None, hash_id=None, hash_id_columns=None, extracts=None, if_not_exists=False, replace=False, ignore=False, transform=False, strict=False)[source]¶

使用指定的列创建表。

有关完整详细信息，请参阅显式创建表。

参数：

columns (Dict[str, Any]) – 将列名映射到其类型的字典，例如 {"name": str, "age": int}
pk (Any | None) – 用作主键的列名字符串，或用于包含多个列的复合主键的字符串元组
foreign_keys (Iterable[str | ForeignKey | Tuple[str, str] | Tuple[str, str, str] | Tuple[str, str, str, str]] | List[str | ForeignKey | Tuple[str, str] | Tuple[str, str, str] | Tuple[str, str, str, str]] | None) – 此表的外键定义列表
column_order (List[str] | None) – 指定哪些列应排在前面的列表
not_null (Iterable[str] | None) – 应创建为 NOT NULL 的列列表
defaults (Dict[str, Any] | None) – 指定列默认值的字典
hash_id (str | None) – 用作主键的列名，其中包含其他列的哈希值
hash_id_columns (Iterable[str] | None) – 计算行哈希 ID 时要使用的列列表
extracts (Dict[str, str] | List[str] | None) – 插入时要提取到单独表中的列列表或字典，参见在插入/upsert 期间自动填充查找表
if_not_exists (bool) – 使用 CREATE TABLE IF NOT EXISTS
replace (bool) – 如果表已存在，则删除并替换
ignore (bool) – 如果表已存在，则静默不做任何操作
transform (bool) – 如果表已存在，则将其转换为符合指定模式
strict (bool) – 对表应用 STRICT 模式

返回类型：

Table

duplicate(new_name)[source]¶

创建此表的副本，复制其模式和所有行数据。

参数：: new_name (str) – 新表的名称
返回类型：: Table

transform(*, types=None, rename=None, drop=None, pk=<sqlite_utils.db.Default object>, not_null=None, defaults=None, drop_foreign_keys=None, add_foreign_keys=None, foreign_keys=None, column_order=None, keep_table=None)[source]¶

应用高级表更改，包括 SQLite 本身不支持的 ALTER TABLE 操作。

有关完整详细信息，请参阅转换表。

参数：

types (dict | None) – 应更改类型的列，例如 {"weight": float}
rename (dict | None) – 要重命名的列，例如 {"headline": "title"}
drop (Iterable | None) – 要删除的列
pk (Any | None) – 表的新主键
not_null (Iterable[str] | None) – 要设置为 NOT NULL 的列
defaults (Dict[str, Any] | None) – 列的默认值
drop_foreign_keys (Iterable[str] | None) – 应移除其外键约束的列的名称
add_foreign_keys (Iterable[str | ForeignKey | Tuple[str, str] | Tuple[str, str, str] | Tuple[str, str, str, str]] | List[str | ForeignKey | Tuple[str, str] | Tuple[str, str, str] | Tuple[str, str, str, str]] | None) – 要添加到表中的外键列表
foreign_keys (Iterable[str | ForeignKey | Tuple[str, str] | Tuple[str, str, str] | Tuple[str, str, str, str]] | List[str | ForeignKey | Tuple[str, str] | Tuple[str, str, str] | Tuple[str, str, str, str]] | None) – 要为表设置的外键列表，将替换任何现有外键
column_order (List[str] | None) – 创建表时用于指定完整或部分列顺序的字符串列表
keep_table (str | None) – 如果指定，现有表将重命名为此名称，并且不会被删除

返回类型：

Table

transform_sql(*, types=None, rename=None, drop=None, pk=<sqlite_utils.db.Default object>, not_null=None, defaults=None, drop_foreign_keys=None, add_foreign_keys=None, foreign_keys=None, column_order=None, tmp_suffix=None, keep_table=None)[source]¶

返回应用此转换所需执行的 SQL 语句列表。

参数：

types (dict | None) – 应更改类型的列，例如 {"weight": float}
rename (dict | None) – 要重命名的列，例如 {"headline": "title"}
drop (Iterable | None) – 要删除的列
pk (Any | None) – 表的新主键
not_null (Iterable[str] | None) – 要设置为 NOT NULL 的列
defaults (Dict[str, Any] | None) – 列的默认值
drop_foreign_keys (Iterable | None) – 应移除其外键约束的列的名称
add_foreign_keys (Iterable[str | ForeignKey | Tuple[str, str] | Tuple[str, str, str] | Tuple[str, str, str, str]] | List[str | ForeignKey | Tuple[str, str] | Tuple[str, str, str] | Tuple[str, str, str, str]] | None) – 要添加到表中的外键列表
foreign_keys (Iterable[str | ForeignKey | Tuple[str, str] | Tuple[str, str, str] | Tuple[str, str, str, str]] | List[str | ForeignKey | Tuple[str, str] | Tuple[str, str, str] | Tuple[str, str, str, str]] | None) – 要为表设置的外键列表，将替换任何现有外键
column_order (List[str] | None) – 创建表时用于指定完整或部分列顺序的字符串列表
tmp_suffix (str | None) – 用于临时表名称的后缀
keep_table (str | None) – 如果指定，现有表将重命名为此名称，并且不会被删除

返回类型：

List[str]

extract(columns, table=None, fk_column=None, rename=None)[source]¶

将指定的列提取到单独的表中。

有关详细信息，请参阅将列提取到单独的表中。

参数：

columns (str | Iterable[str]) – 应提取的单个列或列列表
table (str | None) – 应创建新记录的表的名称
fk_column (str | None) – 要在原始表中填充的外键列的名称
rename (Dict[str, str] | None) – 在填充新表时应重命名的列的字典

返回类型：

Table

create_index(columns, index_name=None, unique=False, if_not_exists=False, find_unique_name=False, analyze=False)[source]¶

在此表上创建索引。

参数：

columns (Iterable[str | DescIndex]) – 要创建索引的单个列或列列表。它们可以是字符串，或者，要创建按降序使用列的索引，可以使用 db.DescIndex(column_name) 对象。
index_name (str | None) – 用于新索引的名称。默认为通过 _ 连接的列名。
unique (bool) – 索引是否应标记为唯一，强制要求唯一值？
if_not_exists (bool) – 仅当不存在具有该名称的索引时才创建。
find_unique_name (bool) – 如果未提供 index_name 并且自动生成的名称已存在，则不断递增后缀数字以找到可用名称。
analyze (bool) – 创建索引后，对此索引运行 ANALYZE。

请参阅创建索引。

add_column(col_name, col_type=None, fk=None, fk_col=None, not_null_default=None)[source]¶

向此表添加列。请参阅添加列。

参数：

col_name (str) – 新列的名称
col_type (Any | None) – 列类型 - Python 类型，例如 str 或 SQLite 类型字符串，例如 "BLOB"
fk (str | None) – 此列应引用为外键的表的名称
fk_col (str | None) – 外键表中此列应引用的列
not_null_default (Any | None) – 将此列设置为 not null 并赋予其此默认值

drop(ignore=False)[source]¶

删除此表。

参数：: ignore (bool) – 设置为 True 可忽略表不存在时的错误

guess_foreign_table(column)[source]¶

对于给定的列，建议另一个可能被此列作为外键引用的表。

例如，名为 tag_id、tag 或 tags 的列可能会建议一个 tag 表，如果存在的话。

如果找不到任何候选，则引发 NoObviousTable 异常。

参数：: column (str) – 列的名称
返回类型：: str

add_foreign_key(column, other_table=None, other_column=None, ignore=False)[source]¶

修改模式以将指定列标记为另一个表的外键。

参数：

column (str) – 要标记为外键的列。
other_table (str | None) – 此列引用的表 - 如果省略，将根据列名猜测。
other_column (str | None) – 其他表中此列引用的列 - 如果省略，将猜测。
ignore (bool) – 将此设置为 True 可忽略已存在的外键 - 否则将引发 AlterError 异常。

enable_counts()[source]¶

设置触发器以更新此表行数的缓存。

有关详细信息，请参阅使用触发器的缓存表计数。

property has_counts_triggers: bool[source]¶: 此表是否已设置触发器以更新缓存计数？

enable_fts(columns, fts_version='FTS5', create_triggers=False, tokenize=None, replace=False)[source]¶

对指定列启用 SQLite 全文搜索。

有关更多详细信息，请参阅全文搜索。

参数：

columns (Iterable[str]) – 要包含在搜索索引中的列名列表。
fts_version (str) – 要使用的 FTS 版本 - 默认为 FTS5，但对于较旧的 SQLite 版本，您可能需要 FTS4。
create_triggers (bool) – 是否应创建触发器以保持搜索索引最新？默认为 False。
tokenize (str | None) – 要使用的自定义 SQLite 分词器，例如 "porter" 可启用 Porter 词干提取。
replace (bool) – 此表的任何现有 FTS 索引是否应被新索引替换？

populate_fts(columns)[source]¶

使用表中指定列的最新数据更新关联的 SQLite 全文搜索索引。

参数：: columns (Iterable[str]) – 要填充数据的列
返回类型：: Table

disable_fts()[source]¶

移除为此表配置的任何全文搜索索引和相关触发器。

返回类型：: Table

rebuild_fts()[source]¶: 对关联的全文搜索索引表运行 rebuild 操作。

detect_fts()[source]¶

检测表是否有对应的 FTS 虚拟表并返回它

返回类型：: str | None

optimize()[source]¶

对关联的全文搜索索引表运行 optimize 操作。

返回类型：: Table

search_sql(columns=None, order_by=None, limit=None, offset=None, where=None, include_rank=False)[source]¶

返回可用于对此表执行搜索的 SQL 字符串。

参数：

columns (Iterable[str] | None) – 要搜索的列
order_by (str | None) – 用于排序的列或 SQL 表达式
limit (int | None) – SQL 限制
offset (int | None) – SQL 偏移量
where (str | None) – WHERE 子句的额外 SQL 片段
include_rank (bool) – 在最终查询中选择搜索排名列

返回类型：

str

search(q, order_by=None, columns=None, limit=None, offset=None, where=None, where_args=None, include_rank=False, quote=False)[source]¶

使用 SQLite 全文搜索对此表执行搜索，为每行返回一个字典序列。

参数：

q (str) – 要搜索的术语
order_by (str | None) – 默认为按排名排序，也可在此处指定列。
columns (Iterable[str] | None) – 要返回的列列表，默认为所有列。
limit (int | None) – 返回行的可选整数限制。
offset (int | None) – 可选整数 SQL 偏移量。
where (str | None) – WHERE 子句的额外 SQL 片段
where_args (Iterable | dict | None) – 用于额外 WHERE 子句中 :param 占位符的参数
include_rank (bool) – 在最终查询中选择搜索排名列
quote (bool) – 应用引用以禁用搜索查询中的任何特殊字符

返回类型：

Generator[dict, None, None]

请参阅使用 table.search() 进行搜索。

delete(pk_values)[source]¶

删除与指定主键匹配的行。

参数：: pk_values (list | tuple | str | int | float) – 单个值，或具有复合主键的表的值元组
返回类型：: Table

delete_where(where=None, where_args=None, analyze=False)[source]¶

删除与指定 where 子句匹配的行，或删除表中的所有行。

请参阅删除多条记录。

参数：

where (str | None) – 要使用的 SQL where 片段，例如 id > ?
where_args (Iterable | dict | None) – 与该片段一起使用的参数 - 对于 id > ? 参数使用迭代器，对于 id > :id 使用字典
analyze (bool) – 设置为 True 可在删除行后运行 ANALYZE。

返回类型：

Table

update(pk_values, updates=None, alter=False, conversions=None)[source]¶

对指定行执行 SQL UPDATE。

请参阅更新特定记录。

参数：

pk_values (list | tuple | str | int | float) – 单个记录的主键 - 如果表有复合主键，可以是元组。
updates (dict | None) – 将列映射到其更新值的字典。
alter (bool) – 设置为 True 可自动添加任何缺失的列。
conversions (dict | None) – 可选字典，包含要在更新期间应用的 SQL 函数，例如 {"mycolumn": "upper(?)"}。

返回类型：

Table

convert(columns, fn, output=None, output_type=None, drop=False, multi=False, where=None, where_args=None, show_progress=False, skip_false=True)[source]¶

将转换函数 fn 应用于指定列中的每个值。

参数：

columns (str | List[str]) – 要转换的单个列或字符串列名列表。
fn (Callable) – 一个可调用对象，接受单个参数 value 并返回转换后的值。
output (str | None) – 可选的字符串列名，用于写入结果（默认为输入列）。
output_type (Any | None) – 如果需要创建输出列，这是用于新列的类型。
drop (bool) – 转换完成后是否应删除原始列？
multi (bool) – 如果 True，则预期 fn(value) 的返回值是一个字典，并且将为该字典的每个键创建新列。
where (str | None) – 用作 WHERE 子句的 SQL 片段，以限制应用转换的行，例如 age > ? 或 age > :age。
where_args (Iterable | dict | None) – 参数列表（如果使用 ?）或字典（如果使用 :age）。
show_progress (bool) – 是否应显示进度条？
skip_false (bool)

请参阅转换列中的数据。

insert(record, pk=<sqlite_utils.db.Default object>, foreign_keys=<sqlite_utils.db.Default object>, column_order=<sqlite_utils.db.Default object>, not_null=<sqlite_utils.db.Default object>, defaults=<sqlite_utils.db.Default object>, hash_id=<sqlite_utils.db.Default object>, hash_id_columns=<sqlite_utils.db.Default object>, alter=<sqlite_utils.db.Default object>, ignore=<sqlite_utils.db.Default object>, replace=<sqlite_utils.db.Default object>, extracts=<sqlite_utils.db.Default object>, conversions=<sqlite_utils.db.Default object>, columns=<sqlite_utils.db.Default object>, strict=<sqlite_utils.db.Default object>)[source]¶

向表中插入单条记录。如果表尚不存在，将根据插入的记录创建具有匹配模式的表，请参阅创建表。

record - 必需：表示要插入记录的字典。

其他参数是可选的，主要影响新表（如果尚不存在）将如何创建。

它们都默认为 DEFAULT，表示应使用当前 Table 对象的默认设置（在表构造函数中指定）。

参数：

record (Dict[str, Any]) – 要插入的字典记录
pk – 如果创建表，哪个列应作为主键。
foreign_keys – 请参阅指定外键。
column_order (List[str] | Default | None) – 创建表时用于指定完整或部分列顺序的字符串列表。
not_null (Iterable[str] | Default | None) – 指定应为 NOT NULL 的列的字符串集合。
defaults (Dict[str, Any] | Default | None) – 指定特定列默认值的字典。
hash_id (str | Default | None) – 要创建并用作主键的列的名称，其中主键的值将作为记录中其他列值的 SHA1 哈希派生。 hash_id="id" 是用于此目的的常用列名。
alter (bool | Default | None) – 布尔值，是否应自动添加任何缺失的列？
ignore (bool | Default | None) – 布尔值，如果已存在具有此主键的记录，则忽略此插入操作。
replace (bool | Default | None) – 布尔值，如果已存在具有此主键的记录，则用此新记录替换它。
extracts (Dict[str, str] | List[str] | Default | None) – 要提取到其他表中的列列表，或将 {column_name: other_table_name} 映射的字典。请参阅在插入/更新时自动填充查找表。
conversions (Dict[str, str] | Default | None) – 指定在插入数据时要应用于数据的 SQL 转换函数的字典，例如 {"name": "upper(?)"}。请参阅使用 SQL 函数转换列值。
columns (Dict[str, Any] | Default | None) – 覆盖用于列的检测到的类型的字典，例如 {"age": int, "weight": float}。
strict (bool | Default | None) – 布尔值，如果在创建表时应用 STRICT 模式。
hash_id_columns (Iterable[str] | Default | None)

返回类型：

Table

insert_all(records, pk=<sqlite_utils.db.Default object>, foreign_keys=<sqlite_utils.db.Default object>, column_order=<sqlite_utils.db.Default object>, not_null=<sqlite_utils.db.Default object>, defaults=<sqlite_utils.db.Default object>, batch_size=<sqlite_utils.db.Default object>, hash_id=<sqlite_utils.db.Default object>, hash_id_columns=<sqlite_utils.db.Default object>, alter=<sqlite_utils.db.Default object>, ignore=<sqlite_utils.db.Default object>, replace=<sqlite_utils.db.Default object>, truncate=False, extracts=<sqlite_utils.db.Default object>, conversions=<sqlite_utils.db.Default object>, columns=<sqlite_utils.db.Default object>, upsert=False, analyze=False, strict=<sqlite_utils.db.Default object>)[source]¶

与 .insert() 类似，但接受记录列表，并确保它创建的表（如果表不存在）包含所有这些数据的列。

使用 analyze=True 可在插入完成后运行 ANALYZE。

返回类型：: Table

upsert(record, pk=<sqlite_utils.db.Default object>, foreign_keys=<sqlite_utils.db.Default object>, column_order=<sqlite_utils.db.Default object>, not_null=<sqlite_utils.db.Default object>, defaults=<sqlite_utils.db.Default object>, hash_id=<sqlite_utils.db.Default object>, hash_id_columns=<sqlite_utils.db.Default object>, alter=<sqlite_utils.db.Default object>, extracts=<sqlite_utils.db.Default object>, conversions=<sqlite_utils.db.Default object>, columns=<sqlite_utils.db.Default object>, strict=<sqlite_utils.db.Default object>)[source]¶

与 .insert() 类似，但执行 UPSERT 操作，根据主键匹配，如果记录不存在则插入，如果存在则更新。

请参阅更新或插入数据（Upserting data）。

返回类型：: Table

upsert_all(records, pk=<sqlite_utils.db.Default object>, foreign_keys=<sqlite_utils.db.Default object>, column_order=<sqlite_utils.db.Default object>, not_null=<sqlite_utils.db.Default object>, defaults=<sqlite_utils.db.Default object>, batch_size=<sqlite_utils.db.Default object>, hash_id=<sqlite_utils.db.Default object>, hash_id_columns=<sqlite_utils.db.Default object>, alter=<sqlite_utils.db.Default object>, extracts=<sqlite_utils.db.Default object>, conversions=<sqlite_utils.db.Default object>, columns=<sqlite_utils.db.Default object>, analyze=False, strict=<sqlite_utils.db.Default object>)[source]¶

与 .upsert() 类似，但可应用于记录列表。

返回类型：: Table

lookup(lookup_values, extra_values=None, pk='id', foreign_keys=None, column_order=None, not_null=None, defaults=None, extracts=None, conversions=None, columns=None, strict=False)[source]¶

使用指定的值创建或填充查找表。

db["Species"].lookup({"name": "Palm"}) 将创建一个名为 Species 的表（如果尚不存在），该表包含两列：id 和 name。它将在 name 列上设置唯一约束，以保证不包含重复行。

然后，它将插入一个新行，其中 name 设置为 Palm，并返回新的整数主键值。

可以提供一个可选的第二个参数，其中包含更多 name: value 对，这些对仅在首次创建记录时包含。对于已存在的记录，后续的 lookup 调用将忽略这些值。

所有其他关键字参数都将传递给 .insert()。

有关更多详细信息，请参阅使用查找表。

参数：

lookup_values (Dict[str, Any]) – 指定用于查找的列名和值的字典
extra_values (Dict[str, Any] | None) – 仅在创建新记录时使用的附加列值
strict (bool | None) – 布尔值，如果在创建表时应用 STRICT 模式。
pk (str | None)
foreign_keys (Iterable[str | ForeignKey | Tuple[str, str] | Tuple[str, str, str] | Tuple[str, str, str, str]] | List[str | ForeignKey | Tuple[str, str] | Tuple[str, str, str] | Tuple[str, str, str, str]] | None)
column_order (List[str] | None)
not_null (Iterable[str] | None)
defaults (Dict[str, Any] | None)
extracts (Dict[str, str] | List[str] | None)
conversions (Dict[str, str] | None)
columns (Dict[str, Any] | None)

m2m(other_table, record_or_iterable=None, pk=<sqlite_utils.db.Default object>, lookup=None, m2m_table=None, alter=False)[source]¶

在表中插入记录后，在其他表中创建一个或多个记录，然后创建多对多记录将原始记录与新创建的记录关联起来。

例如

db["dogs"].insert({"id": 1, "name": "Cleo"}, pk="id").m2m(
    "humans", {"id": 1, "name": "Natalie"}, pk="id"
)

有关详细信息，请参阅使用多对多关系。

参数：

other_table (str | Table) – 要插入新记录的表的名称。
record_or_iterable (Iterable[Dict[str, Any]] | Dict[str, Any] | None) – 要插入的单个字典记录，或记录列表。
pk (Any | Default | None) – 如果创建 other_table，要使用的主键。
lookup (Dict[str, Any] | None) – 与 .lookup() 相同的字典，用于创建多对多查找表。
m2m_table (str | None) – 用于多对多表的字符串名称，默认为根据两个表的名称自动创建。
alter (bool) – 设置为 True 可在 other_table 已存在时为其添加任何缺失的列。

analyze()[source]¶: 对此表运行 ANALYZE

analyze_column(column, common_limit=10, value_truncate=None, total_rows=None, most_common=True, least_common=True)[source]¶

返回关于指定列的统计信息。

请参阅分析列。

参数：

column (str) – 要分析的列
common_limit (int) – 显示此数量的列值
value_truncate – 将常见值的显示截断到此数量的字符
total_rows – 优化 - 传递表中的总行数以避免运行新的 count(*) 查询
most_common (bool) – 如果 True，计算最常见的值
least_common (bool) – 如果 True，计算最不常见的值

返回类型：

ColumnDetails

add_geometry_column(column_name, geometry_type, srid=4326, coord_dimension='XY', not_null=False)[source]¶

在 SpatiaLite 中，几何列只能添加到现有表中。为此，请使用 table.add_geometry_column 并传入几何类型。

默认情况下，这将使用 SRID 4326 添加一个可为空的列。可以使用 column_name、srid 和 not_null 参数进行自定义。

如果列成功添加，返回 True，否则返回 False。

from sqlite_utils.db import Database
from sqlite_utils.utils import find_spatialite

db = Database("mydb.db")
db.init_spatialite(find_spatialite())

# the table must exist before adding a geometry column
table = db["locations"].create({"name": str})
table.add_geometry_column("geometry", "POINT")

参数：

column_name (str) – 要添加的列名
geometry_type (str) – 几何列的类型，例如 "GEOMETRY" 或 "POINT" 或 "POLYGON"
srid (int) – 整数 SRID，WGS84 默认为 4326
coord_dimension (str) – 要使用的维度，默认为 "XY" - 设置为 "XYZ" 可在三维中工作
not_null (bool) – 列是否应为 NOT NULL

返回类型：

bool

create_spatial_index(column_name)[source]¶

空间索引可以显著加快边界框查询。要创建一个，请使用 create_spatial_index 并指定现有几何列的名称。

如果索引成功创建，返回 True，否则返回 False。如果索引已存在，调用此函数是空操作。

# assuming SpatiaLite is loaded, create the table, add the column
table = db["locations"].create({"name": str})
table.add_geometry_column("geometry", "POINT")

# now we can index it
table.create_spatial_index("geometry")

# the spatial index is a virtual table, which we can inspect
print(db["idx_locations_geometry"].schema)
# outputs:
# CREATE VIRTUAL TABLE "idx_locations_geometry" USING rtree(pkid, xmin, xmax, ymin, ymax)

参数：: column_name – 要为其创建空间索引的几何列
返回类型：: bool

sqlite_utils.db.View ¶

class sqlite_utils.db.View(db, name)[source]¶

基类：Queryable

exists()[source]¶: 此表或视图是否存在？

drop(ignore=False)[source]¶

删除此视图。

参数：: ignore – 设置为 True 可忽略视图不存在时的错误

enable_fts(*args, **kwargs)[source]¶: enable_fts() 在表上受支持，但在视图上不受支持。

其他 ¶

sqlite_utils.db.Column ¶

class sqlite_utils.db.Column(cid, name, type, notnull, default_value, is_pk)[source]¶

描述 Table.columns 属性返回的 SQLite 列。

cid: 列索引
name: 列名
type: 列类型
notnull: 列是否具有 not null 约束
default_value: 此列的默认值
is_pk: 此列是否是主键的一部分

sqlite_utils.db.ColumnDetails ¶

class sqlite_utils.db.ColumnDetails(table, column, total_rows, num_null, num_blank, num_distinct, most_common, least_common)[source]¶

关于列的汇总信息，请参阅分析列。

table: 表的名称
column: 列的名称
total_rows: 表中的总行数
num_null: 此列为空值的行数
num_blank: 此列为空（空字符串）的行数
num_distinct: 这列中不同值的数量
most_common: N 个最常见的值，以 (value, count) 元组列表形式返回，如果表中全部是不同值，则返回 None。
least_common: N 个最不常见的值，以 (value, count) 元组列表形式返回，如果表中全部是不同值，或者不同值的数量小于 N (因为它们已经包含在 most_common 中)，则返回 None。

sqlite_utils.utils ¶

sqlite_utils.utils.hash_record ¶

sqlite_utils.utils.hash_record(record, keys=None)[source]¶

record 应该是一个 Python 字典。返回该记录中键和值的 sha1 哈希值。

如果提供了 keys=，则仅使用这些键生成哈希值。

示例用法

from sqlite_utils.utils import hash_record

hashed = hash_record({"name": "Cleo", "twitter": "CleoPaws"})
# Or with the keys= option:
hashed = hash_record(
    {"name": "Cleo", "twitter": "CleoPaws", "age": 7},
    keys=("name", "twitter")
)

参数：

record (Dict) – 要生成哈希值的记录
keys (Iterable[str] | None) – 用于生成哈希值的键子集

sqlite_utils.utils.rows_from_file ¶

sqlite_utils.utils.rows_from_file(fp, format=None, dialect=None, encoding=None, ignore_extras=False, extras_key=None)[source]¶

从一个包含四种不同格式之一的文件类对象中加载字典序列。

from sqlite_utils.utils import rows_from_file
import io

rows, format = rows_from_file(io.StringIO("id,name\n1,Cleo")))
print(list(rows), format)
# Outputs [{'id': '1', 'name': 'Cleo'}] Format.CSV

默认尝试自动检测数据格式，或者可以使用 format= 选项传递明确的格式。

返回一个 (rows_generator, format_used) 元组，其中 rows_generator 可以迭代以返回字典，而 format_used 是 sqlite_utils.utils.Format 枚举中的一个值。

class Format(enum.Enum):
    CSV = 1
    TSV = 2
    JSON = 3
    NL = 4

如果 CSV 或 TSV 文件中的行包含的字段多于头部声明的字段，则在迭代生成器时会引发 sqlite_utils.utils.RowError 异常。

你可以通过传递 ignore_extras=True 来忽略额外的数据。

或者传递 extras_key="rest" 将这些额外的值放入一个名为 rest 的键对应的列表中。

参数：

fp (BinaryIO) – 包含二进制数据的文件类对象
format (Format | None) – 要使用的格式 - 省略此项以检测格式
dialect (Type[Dialect] | None) – 要使用的 CSV 变体 - 省略此项以检测变体
encoding (str | None) – 读取 CSV/TSV 数据时使用的字符编码
ignore_extras (bool | None) – 忽略行中的任何额外字段
extras_key (str | None) – 使用此键将任何额外字段放入列表中

返回类型：

Tuple[Iterable[dict], Format]

sqlite_utils.utils.TypeTracker ¶

class sqlite_utils.utils.TypeTracker[source]¶

封装一个字典迭代器，并跟踪哪些 SQLite 列类型最有可能适合它们的每个键。

示例用法

from sqlite_utils.utils import TypeTracker
import sqlite_utils

db = sqlite_utils.Database(memory=True)
tracker = TypeTracker()
rows = [{"id": "1", "name": "Cleo", "id": "2", "name": "Cardi"}]
db["creatures"].insert_all(tracker.wrap(rows))
print(tracker.types)
# Outputs {'id': 'integer', 'name': 'text'}
db["creatures"].transform(types=tracker.types)

wrap(iterator)[source]¶

使用此方法遍历现有迭代器，并在迭代过程中跟踪列类型。

参数：: iterator (Iterable[dict]) – 要封装的迭代器
返回类型：: Iterable[dict]

property types: Dict[str, str][source]¶: 一个将列名映射到其检测到的类型的字典。这可以传递给 db[table_name].transform(types=tracker.types) 方法。

sqlite_utils.utils.chunks ¶

sqlite_utils.utils.chunks(sequence, size)[source]¶

按给定大小迭代序列的块。

参数：

sequence (Iterable) – 任何 Python 迭代器
size (int) – 每个块的大小

返回类型：

Iterable[Iterable]

sqlite_utils.utils.flatten ¶

sqlite_utils.utils.flatten(row)[source]¶

将嵌套字典（例如 {"a": {"b": 1}}）转换为扁平字典：{"a_b": 1}

参数：: row (dict) – 一个 Python 字典，可选包含嵌套字典
返回类型：: dict