SQL and Generic Functions — SQLAlchemy 0.8 Documentation

# SQLAlchemy 0.8 Documentation

Search:
Release: 0.8.5 | Release Date: February 19, 2014

# SQL and Generic Functions

SQL functions which are known to SQLAlchemy with regards to database-specific rendering, return types and argument behavior. Generic functions are invoked like all SQL functions, using the `func` attribute:

    select([func.count()]).select_from(sometable)

Note that any name not known to `func` generates the function name as is - there is no restriction on what SQL functions can be called, known or unknown to SQLAlchemy, built-in or user defined. The section here only describes those functions where SQLAlchemy already knows what argument and return types are in use.

class `sqlalchemy.sql.functions.` `AnsiFunction`(**kwargs)

  Bases: `sqlalchemy.sql.functions.GenericFunction`

  `identifier` = 'AnsiFunction'
  `name` = 'AnsiFunction'

class `sqlalchemy.sql.functions.` `GenericFunction`(*args, **kwargs)

  Bases: `sqlalchemy.sql.expression.Function`

  Define a ‘generic’ function.

  A generic function is a pre-established `Function` class that is instantiated automatically when called by name from the `func` attribute. Note that calling any name from `func` has the effect that a new `Function` instance is created automatically, given that name. The primary use case for defining a `GenericFunction` class is so that a function of a particular name may be given a fixed return type. It can also include custom argument parsing schemes as well as additional methods.

  Subclasses of `GenericFunction` are automatically registered under the name of the class. For example, a user-defined function `as_utc()` would be available immediately:

      from sqlalchemy.sql.functions import GenericFunction
      from sqlalchemy.types import DateTime

      class as_utc(GenericFunction):
          type = DateTime

      print select([func.as_utc()])

  User-defined generic functions can be organized into packages by specifying the “package” attribute when defining `GenericFunction`. Third party libraries containing many functions may want to use this in order to avoid name conflicts with other systems. For example, if our `as_utc()` function were part of a package “time”:

      class as_utc(GenericFunction):
          type = DateTime
          package = "time"

  The above function would be available from `func` using the package name `time`:

      print select([func.time.as_utc()])

  A final option is to allow the function to be accessed from one name in `func` but to render as a different name. The `identifier` attribute will override the name used to access the function as loaded from `func`, but will retain the usage of `name` as the rendered name:

      class GeoBuffer(GenericFunction):
          type = Geometry
          package = "geo"
          name = "ST_Buffer"
          identifier = "buffer"

  The above function will render as follows:

      >>> print func.geo.buffer()
      ST_Buffer()

  New in version 0.8: `GenericFunction` now supports automatic registration of new functions as well as package and custom naming support.

  Changed in version 0.8: The attribute name `type` is used to specify the function’s return type at the class level. Previously, the name `__return_type__` was used. This name is still recognized for backwards-compatibility.

  `coerce_arguments` = True
  `identifier` = 'GenericFunction'
  `name` = 'GenericFunction'

class `sqlalchemy.sql.functions.` `ReturnTypeFromArgs`(*args, **kwargs)

  Bases: `sqlalchemy.sql.functions.GenericFunction`

  Define a function whose return type is the same as its arguments.

  `identifier` = 'ReturnTypeFromArgs'
  `name` = 'ReturnTypeFromArgs'

class `sqlalchemy.sql.functions.` `char_length`(arg, **kwargs)

  Bases: `sqlalchemy.sql.functions.GenericFunction`

  `identifier` = 'char_length'
  `name` = 'char_length'
  `type`

    alias of `Integer`

class `sqlalchemy.sql.functions.` `coalesce`(*args, **kwargs)

  Bases: `sqlalchemy.sql.functions.ReturnTypeFromArgs`

  `identifier` = 'coalesce'
  `name` = 'coalesce'

class `sqlalchemy.sql.functions.` `concat`(*args, **kwargs)

  Bases: `sqlalchemy.sql.functions.GenericFunction`

  `identifier` = 'concat'
  `name` = 'concat'
  `type`

    alias of `String`

class `sqlalchemy.sql.functions.` `count`(expression=None, **kwargs)

  Bases: `sqlalchemy.sql.functions.GenericFunction`

  The ANSI COUNT aggregate function. With no arguments, emits COUNT *.

  `identifier` = 'count'
  `name` = 'count'
  `type`

    alias of `Integer`

class `sqlalchemy.sql.functions.` `current_date`(**kwargs)

  Bases: `sqlalchemy.sql.functions.AnsiFunction`

  `identifier` = 'current_date'
  `name` = 'current_date'
  `type`

    alias of `Date`

class `sqlalchemy.sql.functions.` `current_time`(**kwargs)

  Bases: `sqlalchemy.sql.functions.AnsiFunction`

  `identifier` = 'current_time'
  `name` = 'current_time'
  `type`

    alias of `Time`

class `sqlalchemy.sql.functions.` `current_timestamp`(**kwargs)

  Bases: `sqlalchemy.sql.functions.AnsiFunction`

  `identifier` = 'current_timestamp'
  `name` = 'current_timestamp'
  `type`

    alias of `DateTime`

class `sqlalchemy.sql.functions.` `current_user`(**kwargs)

  Bases: `sqlalchemy.sql.functions.AnsiFunction`

  `identifier` = 'current_user'
  `name` = 'current_user'
  `type`

    alias of `String`

class `sqlalchemy.sql.functions.` `localtime`(**kwargs)

  Bases: `sqlalchemy.sql.functions.AnsiFunction`

  `identifier` = 'localtime'
  `name` = 'localtime'
  `type`

    alias of `DateTime`

class `sqlalchemy.sql.functions.` `localtimestamp`(**kwargs)

  Bases: `sqlalchemy.sql.functions.AnsiFunction`

  `identifier` = 'localtimestamp'
  `name` = 'localtimestamp'
  `type`

    alias of `DateTime`

class `sqlalchemy.sql.functions.` `max`(*args, **kwargs)

  Bases: `sqlalchemy.sql.functions.ReturnTypeFromArgs`

  `identifier` = 'max'
  `name` = 'max'

class `sqlalchemy.sql.functions.` `min`(*args, **kwargs)

  Bases: `sqlalchemy.sql.functions.ReturnTypeFromArgs`

  `identifier` = 'min'
  `name` = 'min'

class `sqlalchemy.sql.functions.` `next_value`(seq, **kw)

  Bases: `sqlalchemy.sql.functions.GenericFunction`

  Represent the ‘next value’, given a `Sequence` as it’s single argument.

  Compiles into the appropriate function on each backend, or will raise NotImplementedError if used on a backend that does not provide support for sequences.

  `identifier` = 'next_value'
  `name` = 'next_value'
  `type` = Integer()

class `sqlalchemy.sql.functions.` `now`(*args, **kwargs)

  Bases: `sqlalchemy.sql.functions.GenericFunction`

  `identifier` = 'now'
  `name` = 'now'
  `type`

    alias of `DateTime`

class `sqlalchemy.sql.functions.` `random`(*args, **kwargs)

  Bases: `sqlalchemy.sql.functions.GenericFunction`

  `identifier` = 'random'
  `name` = 'random'

`sqlalchemy.sql.functions.` `register_function`(identifier, fn, package='_default')

  Associate a callable with a particular func. name.

  This is normally called by _GenericMeta, but is also available by itself so that a non-Function construct can be associated with the `func` accessor (i.e. CAST, EXTRACT).

class `sqlalchemy.sql.functions.` `session_user`(**kwargs)

  Bases: `sqlalchemy.sql.functions.AnsiFunction`

  `identifier` = 'session_user'
  `name` = 'session_user'
  `type`

    alias of `String`

class `sqlalchemy.sql.functions.` `sum`(*args, **kwargs)

  Bases: `sqlalchemy.sql.functions.ReturnTypeFromArgs`

  `identifier` = 'sum'
  `name` = 'sum'

class `sqlalchemy.sql.functions.` `sysdate`(**kwargs)

  Bases: `sqlalchemy.sql.functions.AnsiFunction`

  `identifier` = 'sysdate'
  `name` = 'sysdate'
  `type`

    alias of `DateTime`

class `sqlalchemy.sql.functions.` `user`(**kwargs)

  Bases: `sqlalchemy.sql.functions.AnsiFunction`

  `identifier` = 'user'
  `name` = 'user'
  `type`

    alias of `String`