SqlAlchemy 2.0 中文文档(五十二)(2)https://developer.aliyun.com/article/1563141
SQL Server 数据类型
与所有 SQLAlchemy 方言一样,所有已知与 SQL Server 有效的大写类型都可以从顶级方言导入,无论它们是来自sqlalchemy.types
还是来自本地方言:
from sqlalchemy.dialects.mssql import ( BIGINT, BINARY, BIT, CHAR, DATE, DATETIME, DATETIME2, DATETIMEOFFSET, DECIMAL, DOUBLE_PRECISION, FLOAT, IMAGE, INTEGER, JSON, MONEY, NCHAR, NTEXT, NUMERIC, NVARCHAR, REAL, SMALLDATETIME, SMALLINT, SMALLMONEY, SQL_VARIANT, TEXT, TIME, TIMESTAMP, TINYINT, UNIQUEIDENTIFIER, VARBINARY, VARCHAR, )
以下是特定于 SQL Server 或具有 SQL Server 特定构造参数的类型:
对象名称 | 描述 |
BIT | MSSQL BIT 类型。 |
DATETIME2 | |
DATETIMEOFFSET | |
DOUBLE_PRECISION | SQL Server DOUBLE PRECISION 数据类型。 |
IMAGE | |
JSON | MSSQL JSON 类型。 |
MONEY | |
NTEXT | MSSQL NTEXT 类型,用于最多 2³⁰ 个字符的可变长度 Unicode 文本。 |
REAL | SQL Server REAL 数据类型。 |
ROWVERSION | 实现 SQL Server ROWVERSION 类型。 |
SMALLDATETIME | |
SMALLMONEY | |
SQL_VARIANT | |
TIME | |
TIMESTAMP | 实现 SQL Server TIMESTAMP 类型。 |
TINYINT | |
UNIQUEIDENTIFIER | |
XML | MSSQL XML 类型。 |
class sqlalchemy.dialects.mssql.BIT
MSSQL BIT 类型。
pyodbc 和 pymssql 都将 BIT 列的值作为 Python 返回,因此只需子类化 Boolean。
成员
init()
类签名
类sqlalchemy.dialects.mssql.BIT
(sqlalchemy.types.Boolean
)
method __init__(create_constraint: bool = False, name: str | None = None, _create_events: bool = True, _adapted_from: SchemaType | None = None)
继承自 sqlalchemy.types.Boolean.__init__
方法的 Boolean
构造一个布尔值。
参数:
create_constraint
–
默认为 False。如果布尔值生成为 int/smallint,则还会在表上创建一个 CHECK 约束,确保值为 1 或 0。
注意
强烈建议 CHECK 约束具有显式名称,以支持模式管理问题。这可以通过设置Boolean.name
参数或设置适当的命名约定来实现;有关背景信息,请参阅配置约束命名约定。
从版本 1.4 开始更改:- 此标志现在默认为 False,表示对于非本地枚举类型不会生成 CHECK 约束。name
– 如果生成 CHECK 约束,请指定约束的名称。
class sqlalchemy.dialects.mssql.CHAR
SQL CHAR 类型。
类签名
类 sqlalchemy.dialects.mssql.CHAR
(sqlalchemy.types.String
)
method __init__(length: int | None = None, collation: str | None = None)
继承自 sqlalchemy.types.String.__init__
方法的 String
创建一个持有字符串的类型。
参数:
length
– 可选,用于 DDL 和 CAST 表达式中的列的长度。如果不会发出CREATE TABLE
,则可以安全地省略。某些数据库可能需要在 DDL 中使用length
,如果包含没有长度的VARCHAR
,则在发出CREATE TABLE
DDL 时会引发异常。值是以字节还是字符解释是特定于数据库的。collation
–
可选,用于 DDL 和 CAST 表达式中的列级排序。使用 SQLite、MySQL 和 PostgreSQL 支持的 COLLATE 关键字进行呈现。例如:
>>> from sqlalchemy import cast, select, String >>> print(select(cast('some string', String(collation='utf8')))) SELECT CAST(:param_1 AS VARCHAR COLLATE utf8) AS anon_1
- 注意
在大多数情况下,Unicode
或UnicodeText
数据类型应该用于预期存储非 ASCII 数据的Column
。这些数据类型将确保在数据库上使用正确的类型。
class sqlalchemy.dialects.mssql.DATETIME2
类签名
类 sqlalchemy.dialects.mssql.DATETIME2
(sqlalchemy.dialects.mssql.base._DateTimeBase
, sqlalchemy.types.DateTime
)
class sqlalchemy.dialects.mssql.DATETIMEOFFSET
类签名
类 sqlalchemy.dialects.mssql.DATETIMEOFFSET
(sqlalchemy.dialects.mssql.base._DateTimeBase
, sqlalchemy.types.DateTime
)
class sqlalchemy.dialects.mssql.DOUBLE_PRECISION
SQL Server DOUBLE PRECISION 数据类型。
新版本 2.0.11 中新增。
类签名
类 sqlalchemy.dialects.mssql.DOUBLE_PRECISION
(sqlalchemy.types.DOUBLE_PRECISION
)
class sqlalchemy.dialects.mssql.IMAGE
成员
init()
类签名
类 sqlalchemy.dialects.mssql.IMAGE
(sqlalchemy.types.LargeBinary
)
method __init__(length: int | None = None)
继承自 sqlalchemy.types.LargeBinary.__init__
方法的 LargeBinary
构造一个 LargeBinary 类型。
参数:
length – 可选,用于 DDL 语句的列长度,用于那些接受长度的二进制类型,例如 MySQL BLOB 类型。
class sqlalchemy.dialects.mssql.JSON
MSSQL JSON 类型。
MSSQL 支持 JSON 格式的数据,自 SQL Server 2016 起。
DDL 级别的 JSON
数据类型将以 NVARCHAR(max)
形式表示数据类型,但也提供了 JSON 级别的比较函数以及 Python 强制转换行为。
自动使用 JSON
每当基础 JSON
数据类型针对 SQL Server 后端使用时。
另请参阅
JSON
- 通用跨平台 JSON 数据类型的主要文档。
JSON
类型支持将 JSON 值持久化存储,以及通过将操作适配到数据库级别的 JSON_VALUE
或 JSON_QUERY
函数来提供的核心索引操作,以支持 JSON
数据类型。
SQL Server JSON
类型在查询 JSON 对象元素时必然使用 JSON_QUERY
和 JSON_VALUE
函数。这两个函数有一个主要限制,即它们根据要返回的对象类型是互斥的。JSON_QUERY
函数仅返回 JSON 字典或列表,但不返回单个字符串、数值或布尔值元素;JSON_VALUE
函数仅返回单个字符串、数值或布尔值元素。如果它们没有针对正确的预期值使用,这两个函数都会返回 NULL 或引发错误。
为了处理这个尴尬的要求,索引访问规则如下:
- 当从一个 JSON 中提取一个子元素,该 JSON 本身是一个 JSON 字典或列表时,应使用
Comparator.as_json()
访问器:
stmt = select( data_table.c.data["some key"].as_json() ).where( data_table.c.data["some key"].as_json() == {"sub": "structure"} )
- 从 JSON 中提取平面布尔值、字符串、整数或浮点数的子元素时,使用以下适当的方法之一:
Comparator.as_boolean()
,Comparator.as_string()
,Comparator.as_integer()
,Comparator.as_float()
:
stmt = select( data_table.c.data["some key"].as_string() ).where( data_table.c.data["some key"].as_string() == "some string" )
版本 1.4 中的新功能。
成员
init()
类签名
类 sqlalchemy.dialects.mssql.JSON
(sqlalchemy.types.JSON
)
method __init__(none_as_null: bool = False)
继承自 JSON
方法 sqlalchemy.types.JSON.__init__
构造一个 JSON
类型。
参数:
none_as_null=False –
如果为 True,则将值None
持久化为 SQL NULL 值,而不是null
的 JSON 编码。注意,当此标志为 False 时,null()
构造仍然可以用于持久化 NULL 值,可以直接将其作为参数值传递,该值由 JSON
类型特别解释为 SQL NULL:
from sqlalchemy import null conn.execute(table.insert(), {"data": null()})
注意
JSON.none_as_null
不适用于传递给 Column.default
和 Column.server_default
的值;这些参数的传递值为 None
意味着“没有默认值”。
此外,当用于 SQL 比较表达式时,Python 值 None
仍然指代 SQL null,而不是 JSON NULL。JSON.none_as_null
标志明确指的是在 INSERT 或 UPDATE 语句中值的持久化。 JSON.NULL
值应用于希望与 JSON null 进行比较的 SQL 表达式。
另请参阅
JSON.NULL
class sqlalchemy.dialects.mssql.MONEY
类签名
类 sqlalchemy.dialects.mssql.MONEY
(sqlalchemy.types.TypeEngine
)
class sqlalchemy.dialects.mssql.NCHAR
SQL NCHAR 类型。
类签名
类 sqlalchemy.dialects.mssql.NCHAR
(sqlalchemy.types.Unicode
)
method __init__(length: int | None = None, collation: str | None = None)
继承自 sqlalchemy.types.String.__init__
方法
创建一个保存字符串的类型。
参数:
length
– 可选,用于 DDL 和 CAST 表达式中的列长度。如果不会发出CREATE TABLE
,则可以安全地省略。某些数据库可能需要在 DDL 中使用长度,并且如果包含没有长度的VARCHAR
,则在发出CREATE TABLE
DDL 时会引发异常。值是以字节还是字符解释是特定于数据库的。collation
–
可选,用于 DDL 和 CAST 表达式中的列级排序。使用 SQLite、MySQL 和 PostgreSQL 支持的 COLLATE 关键字进行呈现。例如:
>>> from sqlalchemy import cast, select, String >>> print(select(cast('some string', String(collation='utf8')))) SELECT CAST(:param_1 AS VARCHAR COLLATE utf8) AS anon_1
- 注意
在大多数情况下,应该使用Unicode
或UnicodeText
数据类型来存储非 ASCII 数据的Column
。这些数据类型将确保在数据库上使用正确的类型。
class sqlalchemy.dialects.mssql.NTEXT
MSSQL NTEXT 类型,用于最多 2³⁰ 个字符的可变长度 Unicode 文本。
成员
init()
类签名
类 sqlalchemy.dialects.mssql.NTEXT
(sqlalchemy.types.UnicodeText
)
method __init__(length: int | None = None, collation: str | None = None)
继承自 sqlalchemy.types.String.__init__
方法
创建一个保存字符串的类型。
参数:
length
– 可选,用于 DDL 和 CAST 表达式中的列长度。如果不会发出CREATE TABLE
,则可以安全地省略。某些数据库可能需要在 DDL 中使用长度,并且如果包含没有长度的VARCHAR
,则在发出CREATE TABLE
DDL 时会引发异常。值是以字节还是字符解释是特定于数据库的。collation
–
可选,用于 DDL 和 CAST 表达式中的列级排序。使用 SQLite、MySQL 和 PostgreSQL 支持的 COLLATE 关键字进行��现。例如:
>>> from sqlalchemy import cast, select, String >>> print(select(cast('some string', String(collation='utf8')))) SELECT CAST(:param_1 AS VARCHAR COLLATE utf8) AS anon_1
- 注意
在大多数情况下,应使用Unicode
或UnicodeText
数据类型来存储非 ASCII 数据的Column
。这些数据类型将确保在数据库上使用正确的类型。
class sqlalchemy.dialects.mssql.NVARCHAR
SQL NVARCHAR 类型。
类签名
类 sqlalchemy.dialects.mssql.NVARCHAR
(sqlalchemy.types.Unicode
)
method __init__(length: int | None = None, collation: str | None = None)
继承自 String
的 sqlalchemy.types.String.__init__
方法
创建一个字符串持有类型。
参数:
length
– 可选,用于 DDL 和 CAST 表达式中的列长度。如果不会发出CREATE TABLE
,则可以安全地省略。某些数据库可能需要在 DDL 中使用长度,并且当包含没有长度的VARCHAR
时,将在发出CREATE TABLE
DDL 时引发异常。该值被解释为字节还是字符是特定于数据库的。collation
–
可选,用于 DDL 和 CAST 表达式中的列级排序。使用 SQLite、MySQL 和 PostgreSQL 支持的 COLLATE 关键字呈现。例如:
>>> from sqlalchemy import cast, select, String >>> print(select(cast('some string', String(collation='utf8')))) SELECT CAST(:param_1 AS VARCHAR COLLATE utf8) AS anon_1
- 注意
在大多数情况下,应使用Unicode
或UnicodeText
数据类型来存储非 ASCII 数据的Column
。这些数据类型将确保在数据库上使用正确的类型。
class sqlalchemy.dialects.mssql.REAL
SQL Server REAL 数据类型。
类签名
类sqlalchemy.dialects.mssql.REAL
(sqlalchemy.types.REAL
)
class sqlalchemy.dialects.mssql.ROWVERSION
实现 SQL Server ROWVERSION 类型。
ROWVERSION 数据类型是 TIMESTAMP 数据类型的 SQL Server 同义词,但当前 SQL Server 文档建议将 ROWVERSION 用于未来的新数据类型。
ROWVERSION 数据类型不会从数据库中反映出来,返回的数据类型将是 TIMESTAMP
。
这是一种只读数据类型,不支持插入值。
版本 1.2 中的新功能。
另请参阅
TIMESTAMP
成员
init()
类签名
类 sqlalchemy.dialects.mssql.ROWVERSION
(sqlalchemy.dialects.mssql.base.TIMESTAMP
)
method __init__(convert_int=False)
从 TIMESTAMP
的 sqlalchemy.dialects.mssql.base.TIMESTAMP.__init__
方法继承
构造一个 TIMESTAMP 或 ROWVERSION 类型。
参数:
convert_int – 如果为 True,则在读取时将二进制整数值转换为整数。
新版本 1.2。
class sqlalchemy.dialects.mssql.SMALLDATETIME
成员
init()
类签名
类 sqlalchemy.dialects.mssql.SMALLDATETIME
(sqlalchemy.dialects.mssql.base._DateTimeBase
,sqlalchemy.types.DateTime
)
method __init__(timezone: bool = False)
从 DateTime
的 sqlalchemy.types.DateTime.__init__
方法继承
构造一个新的DateTime
。
参数:
时区 – 布尔值。指示日期时间类型是否应在仅在基础日期/时间持有类型上可用时启用时区支持。建议在使用此标志时直接使用TIMESTAMP
数据类型,因为一些数据库包括与时区功能的 TIMESTAMP 数据类型不同的单独的通用日期/时间持有类型,如 Oracle。
class sqlalchemy.dialects.mssql.SMALLMONEY
类签名
类 sqlalchemy.dialects.mssql.SMALLMONEY
(sqlalchemy.types.TypeEngine
)
class sqlalchemy.dialects.mssql.SQL_VARIANT
类签名
类 sqlalchemy.dialects.mssql.SQL_VARIANT
(sqlalchemy.types.TypeEngine
)
class sqlalchemy.dialects.mssql.TEXT
SQL TEXT 类型。
类签名
类 sqlalchemy.dialects.mssql.TEXT
(sqlalchemy.types.Text
)
method __init__(length: int | None = None, collation: str | None = None)
从 String
的 sqlalchemy.types.String.__init__
方法继承
创建一个字符串持有类型。
参数:
length
– 可选项,用于 DDL 和 CAST 表达式中的列长度。如果不会发出CREATE TABLE
,可以安全地省略。某些数据库可能需要在 DDL 中使用长度,并且如果包含一个没有长度的VARCHAR
,则在发出CREATE TABLE
DDL 时会引发异常。值是作为字节还是字符解释的是特定于数据库的。collation
–
可选项,用于 DDL 和 CAST 表达式中的列级排序。使用 SQLite、MySQL 和 PostgreSQL 支持的 COLLATE 关键字进行呈现。例如:
>>> from sqlalchemy import cast, select, String >>> print(select(cast('some string', String(collation='utf8')))) SELECT CAST(:param_1 AS VARCHAR COLLATE utf8) AS anon_1
- 注意
在大多数情况下,应该使用Unicode
或UnicodeText
数据类型来存储非 ASCII 数据的Column
。这些数据类型将确保在数据库中使用正确的类型。
class sqlalchemy.dialects.mssql.TIME
类签名
类sqlalchemy.dialects.mssql.TIME
(sqlalchemy.types.TIME
)
class sqlalchemy.dialects.mssql.TIMESTAMP
实现 SQL Server TIMESTAMP 类型。
请注意,这与 SQL 标准 TIMESTAMP 类型完全不同,SQL Server 不支持该类型。它是一个只读数据类型,不支持插入值。
新功能在版本 1.2 中引入。
另请参阅
ROWVERSION
成员
init()
类签名
类sqlalchemy.dialects.mssql.TIMESTAMP
(sqlalchemy.types._Binary
)
method __init__(convert_int=False)
构造 TIMESTAMP 或 ROWVERSION 类型。
参数:
convert_int – 如果为 True,则二进制整数值将在读取时转换为整数。
新功能在版本 1.2 中引入。
class sqlalchemy.dialects.mssql.TINYINT
类签名
类sqlalchemy.dialects.mssql.TINYINT
(sqlalchemy.types.Integer
)
class sqlalchemy.dialects.mssql.UNIQUEIDENTIFIER
成员
init()
类签名
类sqlalchemy.dialects.mssql.UNIQUEIDENTIFIER
(sqlalchemy.types.Uuid
)
method __init__(as_uuid: bool = True)
构造 UNIQUEIDENTIFIER
类型。
参数:
as_uuid=True –
如果为 True,则值将被解释为 Python uuid 对象,通过 DBAPI 转换为/从字符串。
class sqlalchemy.dialects.mssql.VARBINARY
MSSQL VARBINARY 类型。
该类型为核心的VARBINARY
类型添加了额外的功能,包括“deprecate_large_types”模式,其中会渲染VARBINARY(max)
或 IMAGE,以及 SQL Server 的FILESTREAM
选项。
另请参见
大型文本/二进制类型弃用
类签名
类 sqlalchemy.dialects.mssql.VARBINARY
(sqlalchemy.types.VARBINARY
, sqlalchemy.types.LargeBinary
)
method __init__(length=None, filestream=False)
构造一个 VARBINARY 类型。
参数:
length
– 可选参数,在 DDL 语句中用于列长度,用于那些接受长度参数的二进制类型,比如 MySQL 的 BLOB 类型。filestream=False
–
如果为 True,在表定义中会渲染FILESTREAM
关键字。在这种情况下,length
必须为None
或者'max'
。
新于 1.4.31 版本。
class sqlalchemy.dialects.mssql.VARCHAR
SQL VARCHAR 类型。
类签名
类 sqlalchemy.dialects.mssql.VARCHAR
(sqlalchemy.types.String
)
method __init__(length: int | None = None, collation: str | None = None)
从 String
的 sqlalchemy.types.String.__init__
方法继承
创建一个保存字符串的类型。
参数:
length
– 可选参数,在 DDL 和 CAST 表达式中用于列长度。如果不会发出CREATE TABLE
,可以安全地省略。某些数据库可能需要 DDL 中使用长度,并且如果包括了没有长度的VARCHAR
,则在发出CREATE TABLE
DDL 时会引发异常。值是以字节还是字符解释的,这取决于数据库。collation
–
可选参数,在 DDL 和 CAST 表达式中用于列级别的排序。使用 SQLite、MySQL 和 PostgreSQL 支持的 COLLATE 关键字渲染。例如:
>>> from sqlalchemy import cast, select, String >>> print(select(cast('some string', String(collation='utf8')))) SELECT CAST(:param_1 AS VARCHAR COLLATE utf8) AS anon_1
- 注意
在大多数情况下,Unicode
或者UnicodeText
数据类型应该用于预期存储非 ASCII 数据的Column
。这些数据类型将确保在数据库上使用正确的类型。
class sqlalchemy.dialects.mssql.XML
MSSQL XML 类型。
这是一个占位符类型,用于反射目的,不包括任何 Python 端数据类型支持。它也不支持额外的参数,比如“CONTENT”、“DOCUMENT”、“xml_schema_collection”。
成员
init()
类签名
类 sqlalchemy.dialects.mssql.XML
(sqlalchemy.types.Text
)
method __init__(length: int | None = None, collation: str | None = None)
继承自 String
的 sqlalchemy.types.String.__init__
方法
创建一个持有字符串的类型。
参数:
length
– 可选项,用于 DDL 和 CAST 表达式中列的长度。如果不会发出CREATE TABLE
语句,则可以安全地省略。某些数据库可能需要在 DDL 中使用长度,并且如果包括了没有长度的VARCHAR
,则在发出CREATE TABLE
DDL 时会引发异常。值是按字节还是按字符解释,取决于数据库。collation
–
可选项,用于 DDL 和 CAST 表达式中的列级排序。使用 SQLite、MySQL 和 PostgreSQL 支持的 COLLATE 关键字呈现。例如:
>>> from sqlalchemy import cast, select, String >>> print(select(cast('some string', String(collation='utf8')))) SELECT CAST(:param_1 AS VARCHAR COLLATE utf8) AS anon_1
- 注意
在大多数情况下,应该使用Unicode
或UnicodeText
数据类型来存储非 ASCII 数据的Column
。这些数据类型将确保在数据库上使用正确的类型。
SqlAlchemy 2.0 中文文档(五十二)(4)https://developer.aliyun.com/article/1563143