表示SQL JSON类型。
注解
JSON 作为供应商特定JSON类型的外观提供。由于它支持JSON SQL操作,因此它只在具有实际JSON类型的后端上工作,目前:
PostgreSQL-请参阅 JSON 和 JSONB 后端特定注释
MySQL5.7版(MariaDB从10.2系列开始没有)-请参见 JSON 后端特定注释
SQLite自3.9版起-请参阅 JSON 后端特定注释
Microsoft SQL Server 2016及更高版本-请参阅 JSON 后端特定注释
JSON 是支持本地JSON数据类型日益流行的核心的一部分。
这个 JSON 类型存储任意JSON格式的数据,例如:
data_table = Table('data_table', metadata,
Column('id', Integer, primary_key=True),
Column('data', JSON)
)
with engine.connect() as conn:
conn.execute(
data_table.insert(),
data = {"key1": "value1", "key2": "value2"}
)
JSON-Specific Expression Operators
这个 JSON 数据类型提供以下附加的SQL操作:
键控索引操作:
data_table.c.data['some key']
整数索引操作:
data_table.c.data[3]
路径索引操作:
data_table.c.data[('key_1', 'key_2', 5, ..., 'key_n')]
特定JSON元素类型的数据转换器,在调用索引或路径操作之后::
data_table.c.data["some key"].as_integer()
1.3.11 新版功能.
其他操作可以从特定于方言的版本获得 JSON ,如 JSON 和 JSONB 它们都提供了额外的PostgreSQL特定操作。
将JSON元素转换为其他类型
索引操作,即通过使用Python括号运算符调用表达式调用的操作,如 some_column['some key'] ,返回类型默认为的表达式对象 JSON 默认情况下,这样可以对结果类型调用进一步的面向JSON的指令。但是,更常见的情况可能是索引操作返回特定的标量元素,例如字符串或整数。为了以后端不可知的方式提供对这些元素的访问,提供了一系列数据转换器:
这些数据转换器通过支持方言来实现,以确保与上述类型的比较按预期工作,例如:
# integer comparison
data_table.c.data["some_integer_key"].as_integer() == 5
# boolean comparison
data_table.c.data["some_boolean"].as_boolean() == True
1.3.11 新版功能:为基本JSON数据元素类型添加了特定于类型的caster。
注解
data caster函数是版本1.3.11中的新功能,它取代了以前记录的使用CAST的方法;作为参考,它如下所示:
from sqlalchemy import cast, type_coerce
from sqlalchemy import String, JSON
cast(
data_table.c.data['some_key'], String
) == type_coerce(55, JSON)
上述情况现在直接起作用:
data_table.c.data['some_key'].as_integer() == 5
有关1.3.x系列中以前的比较方法的详细信息,请参阅SQLAlchemy 1.2的文档或该版本发行版的doc/目录中包含的HTML文件。
使用ORM时检测JSON列中的更改
这个 JSON 当与sqlAlchemy ORM一起使用时,类型不会检测到结构的就地突变。为了检测到这些, sqlalchemy.ext.mutable 必须使用扩展名。此扩展将允许对数据结构进行“就地”更改,以生成工作单元将检测到的事件。参见中的示例 HSTORE 一个简单的涉及字典的例子。
支持JSON null与SQL null
使用空值时, JSON 类型建议使用两个特定的常量,以便区分计算结果为SQL NULL的列(例如无值)与 "null" . 若要根据SQL为空的值插入或选择,请使用常量 null() ::
from sqlalchemy import null
conn.execute(table.insert(), json_value=null())
根据JSON值插入或选择 "null" ,使用常量 JSON.NULL ::
conn.execute(table.insert(), json_value=JSON.NULL)
这个 JSON 类型支持标志 JSON.none_as_null 当设置为true时,将导致python常量 None 计算为sql null的值,如果设置为false,则会导致python常量 None 评估JSON的值 "null" . python值 None 可与以下两者结合使用: JSON.NULL 和 null() 为了指示空值,但必须注意 JSON.none_as_null 在这些情况下。
自定义JSON序列化程序
使用的JSON序列化程序和反序列化程序 JSON 默认为Python的 json.dumps 和 json.loads 函数;对于psycopg2方言,psycopg2可能正在使用它自己的自定义加载程序函数。
engine = create_engine(
"sqlite://",
json_serializer=lambda obj: json.dumps(obj, ensure_ascii=False))
在 1.3.7 版更改:SQLite方言 json_serializer 和 json_deserializer 参数重命名自 _json_serializer 和 _json_deserializer .
1.1 新版功能.
classComparator(expr)¶
为定义比较操作 JSON .
类签名
class sqlalchemy.types.JSON.Comparator (sqlalchemy.types.Comparator, sqlalchemy.types.Comparator)
将索引值转换为布尔值。
例如。::
stmt = select(
mytable.c.json_column['some_data'].as_boolean()
).where(
mytable.c.json_column['some_data'].as_boolean() == True
)
1.3.11 新版功能.
将索引值转换为浮点值。
例如。::
stmt = select(
mytable.c.json_column['some_data'].as_float()
).where(
mytable.c.json_column['some_data'].as_float() == 29.75
)
1.3.11 新版功能.
将索引值转换为整数。
例如。::
stmt = select(
mytable.c.json_column['some_data'].as_integer()
).where(
mytable.c.json_column['some_data'].as_integer() == 5
)
1.3.11 新版功能.
将索引值转换为JSON。
例如。::
stmt = select(mytable.c.json_column['some_data'].as_json())
这通常是索引元素在任何情况下的默认行为。
请注意,并非所有后端都支持完整JSON结构的比较。
1.3.11 新版功能.
将索引值转换为字符串。
例如。::
stmt = select(
mytable.c.json_column['some_data'].as_string()
).where(
mytable.c.json_column['some_data'].as_string() ==
'some string'
)
1.3.11 新版功能.
classJSONElementType¶
JSON表达式中index/path元素的公共函数。
返回用于处理绑定值的转换函数。
返回一个callable,该callable将接收一个bind参数值作为唯一的位置参数,并返回一个要发送到db-api的值。
如果不需要处理,则该方法应返回 None .
参数
dialect¶ -- 方言实例正在使用中。
返回一个转换函数,用于处理直接呈现而不使用绑定的文本值。
当编译器使用“文本绑定”标志时,通常在生成DDL以及后端不接受绑定参数的某些情况下使用此函数。
0.9.0 新版功能.
methodsqlalchemy.types.JSON.JSONElementType.string_literal_processor(dialect)¶
classJSONIndexType¶
JSON索引值的数据类型的占位符。
这允许执行时处理特殊语法的JSON索引值。
类签名
class sqlalchemy.types.JSON.JSONIndexType (sqlalchemy.types.JSONElementType)
classJSONIntIndexType¶
JSON索引值的数据类型的占位符。
这允许执行时处理特殊语法的JSON索引值。
类签名
classJSONPathType¶
JSON路径操作的占位符类型。
这允许将基于路径的索引值执行时处理为特定的SQL语法。
类签名
class sqlalchemy.types.JSON.JSONPathType (sqlalchemy.types.JSONElementType)
classJSONStrIndexType¶
JSON索引值的数据类型的占位符。
这允许执行时处理特殊语法的JSON索引值。
类签名
attributesqlalchemy.types.JSON.NULL= symbol('JSON_NULL')¶
描述空的JSON值。
此值用于强制 "null" 用作值。python的值 None 将被识别为SQL空值或JSON "null" ,基于 JSON.none_as_null 旗帜; JSON.NULL 常量可用于始终解析为JSON "null" 无论此设置如何。这与 null() 构造,它始终解析为SQL空值。例如。::
from sqlalchemy import null
from sqlalchemy.dialects.postgresql import JSON
# will *always* insert SQL NULL
obj1 = MyObject(json_value=null())
# will *always* insert JSON string "null"
obj2 = MyObject(json_value=JSON.NULL)
session.add_all([obj1, obj2])
session.commit()
为了将JSON NULL设置为列的默认值,最透明的方法是使用 text() ::
Table(
'my_table', metadata,
Column('json_data', JSON, default=text("'null'"))
)
虽然可以使用 JSON.NULL 在这种情况下, JSON.NULL 值将作为列的值返回,在ORM上下文中或默认值的其他重新调整用途中,这可能是不可取的。使用SQL表达式意味着将在检索生成的默认值的上下文中从数据库中重新提取该值。
methodsqlalchemy.types.JSON.__init__(none_as_null=False)¶
构建一个 JSON 类型。
参数
none_as_null=False¶ -- 如果为真,则保持该值 None 作为SQL空值,而不是 null . 请注意,当此标志为false时, null() 构造仍可以用于持久化空值::from sqlAlchemy import null conn.execute(table.insert(),data=null())。。注: JSON.none_as_null 做 not 应用于传递到的值 Column.default 和 Column.server_default 一个值 None 传递这些参数意味着“不存在默认值”。…参阅: JSON.NULL
methodsqlalchemy.types.JSON.bind_processor(dialect)¶
返回用于处理绑定值的转换函数。
返回一个callable,该callable将接收一个bind参数值作为唯一的位置参数,并返回一个要发送到db-api的值。
如果不需要处理,则该方法应返回 None .
参数
dialect¶ -- 方言实例正在使用中。
methodsqlalchemy.types.JSON.result_processor(dialect, coltype)¶
返回用于处理结果行值的转换函数。
返回一个可调用的,它将接收作为唯一位置参数的结果行列值,并返回一个值以返回给用户。
如果不需要处理,则该方法应返回 None .
参数
dialect¶ -- 方言实例正在使用中。
coltype¶ -- 在cursor.description中接收到dbapi coltype参数。
attributesqlalchemy.types.JSON.should_evaluate_none¶
Alias JSON.none_as_null