class ARRAY(SchemaEventTarget, Indexable, Concatenable, TypeEngine[
Known subclasses: sqlalchemy.dialects.postgresql.ARRAY
Represent a SQL Array type. .. note:: This type serves as the basis for all ARRAY operations. However, currently **only the PostgreSQL backend has support for SQL arrays in SQLAlchemy**. It is recommended to use the PostgreSQL-specific :class:`sqlalchemy.dialects.postgresql.ARRAY` type directly when using ARRAY types with PostgreSQL, as it provides additional operators specific to that backend. :class:`_types.ARRAY` is part of the Core in support of various SQL standard functions such as :class:`_functions.array_agg` which explicitly involve arrays; however, with the exception of the PostgreSQL backend and possibly some third-party dialects, no other SQLAlchemy built-in dialect has support for this type. An :class:`_types.ARRAY` type is constructed given the "type" of element:: mytable = Table("mytable", metadata, Column("data", ARRAY(Integer)) ) The above type represents an N-dimensional array, meaning a supporting backend such as PostgreSQL will interpret values with any number of dimensions automatically. To produce an INSERT construct that passes in a 1-dimensional array of integers:: connection.execute( mytable.insert(), {"data": [1,2,3]} ) The :class:`_types.ARRAY` type can be constructed given a fixed number of dimensions:: mytable = Table("mytable", metadata, Column("data", ARRAY(Integer, dimensions=2)) ) Sending a number of dimensions is optional, but recommended if the datatype is to represent arrays of more than one dimension. This number is used: * When emitting the type declaration itself to the database, e.g. ``INTEGER[][]`` * When translating Python values to database values, and vice versa, e.g. an ARRAY of :class:`.Unicode` objects uses this number to efficiently access the string values inside of array structures without resorting to per-row type inspection * When used with the Python ``getitem`` accessor, the number of dimensions serves to define the kind of type that the ``[]`` operator should return, e.g. for an ARRAY of INTEGER with two dimensions:: >>> expr = table.c.column[5] # returns ARRAY(Integer, dimensions=1) >>> expr = expr[6] # returns Integer For 1-dimensional arrays, an :class:`_types.ARRAY` instance with no dimension parameter will generally assume single-dimensional behaviors. SQL expressions of type :class:`_types.ARRAY` have support for "index" and "slice" behavior. The Python ``[]`` operator works normally here, given integer indexes or slices. Arrays default to 1-based indexing. The operator produces binary expression constructs which will produce the appropriate SQL, both for SELECT statements:: select(mytable.c.data[5], mytable.c.data[2:7]) as well as UPDATE statements when the :meth:`_expression.Update.values` method is used:: mytable.update().values({ mytable.c.data[5]: 7, mytable.c.data[2:7]: [1, 2, 3] }) The :class:`_types.ARRAY` type also provides for the operators :meth:`.types.ARRAY.Comparator.any` and :meth:`.types.ARRAY.Comparator.all`. The PostgreSQL-specific version of :class:`_types.ARRAY` also provides additional operators. .. container:: topic **Detecting Changes in ARRAY columns when using the ORM** The :class:`_sqltypes.ARRAY` type, when used with the SQLAlchemy ORM, does not detect in-place mutations to the array. In order to detect these, the :mod:`sqlalchemy.ext.mutable` extension must be used, using the :class:`.MutableList` class:: from sqlalchemy import ARRAY from sqlalchemy.ext.mutable import MutableList class SomeOrmClass(Base): # ... data = Column(MutableList.as_mutable(ARRAY(Integer))) This extension will allow "in-place" changes such to the array such as ``.append()`` to produce events which will be detected by the unit of work. Note that changes to elements **inside** the array, including subarrays that are mutated in place, are **not** detected. Alternatively, assigning a new array value to an ORM element that replaces the old one will always trigger a change event. .. versionadded:: 1.1.0 .. seealso:: :class:`sqlalchemy.dialects.postgresql.ARRAY`
Class |
|
Define comparison operations for :class:`_types.ARRAY`. |
Method | __init__ |
Construct an :class:`_types.ARRAY`. |
Method | compare |
Compare two values for equality. |
Method | literal |
Return a conversion function for processing literal values that are to be rendered directly without using binds. |
Class Variable | __visit |
Undocumented |
Instance Variable | as |
Undocumented |
Instance Variable | dimensions |
Undocumented |
Instance Variable | item |
Undocumented |
Instance Variable | zero |
If True, Python zero-based indexes should be interpreted as one-based on the SQL expression side. |
Property | hashable |
Flag, if False, means values from this type aren't hashable. |
Property | python |
Return the Python type object expected to be returned by instances of this type, if known. |
Method | _apply |
Helper method that can be used by bind_processor(), literal_processor(), etc. to apply an item processor to elements of an array value, taking into account the 'dimensions' for this array type. |
Method | _set |
Support SchemaEventTarget |
Method | _set |
Support SchemaEventTarget |
Class Variable | _is |
Undocumented |
Inherited from SchemaEventTarget
:
Class Variable | dispatch |
Undocumented |
Inherited from EventTarget
(via SchemaEventTarget
):
Class Variable | __slots__ |
Undocumented |
Inherited from TypeEngineMixin
(via SchemaEventTarget
, EventTarget
, Indexable
, Concatenable
):
Method | adapt |
Undocumented |
Method | dialect |
Undocumented |
Property | _static |
Undocumented |
Inherited from TypeEngine
(via SchemaEventTarget
, EventTarget
, Indexable
, Concatenable
, TypeEngineMixin
):
Method | __repr__ |
Undocumented |
Method | __str__ |
Undocumented |
Method | as |
Return an instance of the generic type corresponding to this type using heuristic rule. The method may be overridden if this heuristic rule is not sufficient. |
Method | bind |
Given a bind value (i.e. a :class:`.BindParameter` instance), return a SQL expression in its place. |
Method | bind |
Return a conversion function for processing bind values. |
Method | coerce |
Suggest a type for a 'coerced' Python value in an expression. |
Method | column |
Given a SELECT column expression, return a wrapping SQL expression. |
Method | compare |
Compare this type against the given backend type. |
Method | compile |
Produce a string-compiled form of this :class:`.TypeEngine`. |
Method | copy |
Undocumented |
Method | copy |
Undocumented |
Method | evaluates |
Return a copy of this type which has the :attr:`.should_evaluate_none` flag set to True. |
Method | get |
Return the corresponding type object from the underlying DB-API, if any. |
Method | result |
Return a conversion function for processing result row values. |
Method | with |
Produce a copy of this type object that will utilize the given type when applied to the dialect of the given name. |
Class Variable | render |
Render bind casts for :attr:`.BindTyping.RENDER_CASTS` mode. |
Class Variable | render |
render casts when rendering a value as an inline literal, e.g. with :meth:`.TypeEngine.literal_processor`. |
Class Variable | should |
If True, the Python constant ``None`` is considered to be handled explicitly by this type. |
Class Variable | sort |
A sorting function that can be passed as the key to sorted. |
Static Method | _to |
Undocumented |
Method | _cached |
Return a dialect-specific bind processor for this type. |
Method | _cached |
return a dialect-specific processing object for custom purposes. |
Method | _cached |
Return a dialect-specific literal processor for this type. |
Method | _cached |
Return a dialect-specific result processor for this type. |
Method | _compare |
Undocumented |
Method | _default |
Undocumented |
Method | _dialect |
Return a dialect-specific registry which caches a dialect-specific implementation, bind processing function, and one or more result processing functions. |
Method | _gen |
Undocumented |
Method | _resolve |
adjust this type given a literal Python value that will be stored in a bound parameter. |
Method | _resolve |
given a Python type (e.g. ``int``, ``str``, etc. ) return an instance of this :class:`.TypeEngine` that's appropriate for this type. |
Method | _unwrapped |
Return the 'unwrapped' dialect impl for this type. |
Class Variable | _is |
Undocumented |
Class Variable | _is |
Undocumented |
Class Variable | _is |
Undocumented |
Class Variable | _isnull |
Undocumented |
Class Variable | _sqla |
Undocumented |
Property | _generic |
Undocumented |
Property | _has |
memoized boolean, check if bind_expression is implemented. |
Property | _has |
memoized boolean, check if column_expression is implemented. |
Property | _type |
Return a rudimental 'affinity' value expressing the general class of type. |
Inherited from Visitable
(via SchemaEventTarget
, EventTarget
, Indexable
, Concatenable
, TypeEngineMixin
, TypeEngine
):
Method | __class |
Undocumented |
Method | __init |
Undocumented |
Class Method | _generate |
Undocumented |
Method | _compiler |
Undocumented |
Class Variable | _original |
Undocumented |
_TypeEngineArgument[ Any]
, as_tuple: bool
= False, dimensions: Optional[ int]
= None, zero_indexes: bool
= False):
(source)
¶
sqlalchemy.dialects.postgresql.ARRAY
Construct an :class:`_types.ARRAY`. E.g.:: Column('myarray', ARRAY(Integer)) Arguments are: :param item_type: The data type of items of this array. Note that dimensionality is irrelevant here, so multi-dimensional arrays like ``INTEGER[][]``, are constructed as ``ARRAY(Integer)``, not as ``ARRAY(ARRAY(Integer))`` or such. :param as_tuple=False: Specify whether return results should be converted to tuples from lists. This parameter is not generally needed as a Python list corresponds well to a SQL array. :param dimensions: if non-None, the ARRAY will assume a fixed number of dimensions. This impacts how the array is declared on the database, how it goes about interpreting Python and result values, as well as how expression behavior in conjunction with the "getitem" operator works. See the description at :class:`_types.ARRAY` for additional detail. :param zero_indexes=False: when True, index values will be converted between Python zero-based and SQL one-based indexes, e.g. a value of one will be added to all index values before passing to the database.
sqlalchemy.dialects.postgresql.ARRAY
Return a conversion function for processing literal values that are to be rendered directly without using binds. This function is used when the compiler makes use of the "literal_binds" flag, typically used in DDL generation as well as in certain scenarios where backends don't accept bound parameters. Returns a callable which will receive a literal Python value as the sole positional argument and will return a string representation to be rendered in a SQL statement. .. note:: This method is only called relative to a **dialect specific type object**, which is often **private to a dialect in use** and is not the same type object as the public facing one, which means it's not feasible to subclass a :class:`.types.TypeEngine` class in order to provide an alternate :meth:`_types.TypeEngine.literal_processor` method, unless subclassing the :class:`_types.UserDefinedType` class explicitly. To provide alternate behavior for :meth:`_types.TypeEngine.literal_processor`, implement a :class:`_types.TypeDecorator` class and provide an implementation of :meth:`_types.TypeDecorator.process_literal_param`. .. seealso:: :ref:`types_typedecorator`
sqlalchemy.dialects.postgresql.ARRAY
If True, Python zero-based indexes should be interpreted as one-based on the SQL expression side.
sqlalchemy.dialects.postgresql.ARRAY
Flag, if False, means values from this type aren't hashable. Used by the ORM when uniquing result lists.
sqlalchemy.dialects.postgresql.ARRAY
Return the Python type object expected to be returned by instances of this type, if known. Basically, for those types which enforce a return type, or are known across the board to do such for all common DBAPIs (like ``int`` for example), will return that type. If a return type is not defined, raises ``NotImplementedError``. Note that any type also accommodates NULL in SQL which means you can also get back ``None`` from any type in practice.
Helper method that can be used by bind_processor(), literal_processor(), etc. to apply an item processor to elements of an array value, taking into account the 'dimensions' for this array type. See the Postgresql ARRAY datatype for usage examples. .. versionadded:: 2.0