.. changelog::
:version: 1.1.0b1
+ .. change::
+ :tags: feature, sql
+ :tickets: 3718
+
+ Added TABLESAMPLE support via the new :meth:`.FromClause.tablesample`
+ method and standalone function. Pull request courtesy Ilja Everilä.
+
+ .. seealso::
+
+ :ref:`change_3718`
+
.. change::
:tags: feature, orm, ext
:ticket:`2857`
+.. _change_3718:
+
+Support for TABLESAMPLE
+-----------------------
+
+The SQL standard TABLESAMPLE can be rendered using the
+:meth:`.FromClause.tablesample` method, which returns a :class:`.TableSample`
+construct similar to an alias::
+
+ from sqlalchemy import func
+
+ selectable = people.tablesample(
+ func.bernoulli(1),
+ name='alias',
+ seed=func.random())
+ stmt = select([selectable.c.people_id])
+
+Assuming ``people`` with a column ``people_id``, the above
+statement would render as::
+
+ SELECT alias.people_id FROM
+ people AS alias TABLESAMPLE bernoulli(:bernoulli_1)
+ REPEATABLE (random())
+
+:ticket:`3718`
+
.. _change_3216:
The ``.autoincrement`` directive is no longer implicitly enabled for a composite primary key column
.. autofunction:: sqlalchemy.sql.expression.table
+.. autofunction:: tablesample
+
.. autofunction:: union
.. autofunction:: union_all
:members:
:inherited-members:
+.. autoclass:: TableSample
+ :members:
+ :inherited-members:
+
.. autoclass:: TextAsFrom
:members:
:inherited-members:
select,
subquery,
table,
+ tablesample,
text,
true,
tuple_,
Select,
Selectable,
TableClause,
+ TableSample,
Update,
alias,
and_,
select,
subquery,
table,
+ tablesample,
text,
true,
True_,
kw['lateral'] = True
return "LATERAL %s" % self.visit_alias(lateral, **kw)
+ def visit_tablesample(self, tablesample, asfrom=False, **kw):
+ text = "%s TABLESAMPLE %s" % (
+ self.visit_alias(tablesample, asfrom=True, **kw),
+ tablesample._get_method()._compiler_dispatch(self, **kw))
+
+ if tablesample.seed is not None:
+ text += " REPEATABLE (%s)" % (
+ tablesample.seed._compiler_dispatch(self, **kw))
+
+ return text
+
def get_render_as_alias_suffix(self, alias_name_text):
return " AS " + alias_name_text
'nullslast',
'or_', 'outparam', 'outerjoin', 'over', 'select', 'subquery',
'table', 'text',
- 'tuple_', 'type_coerce', 'union', 'union_all', 'update', 'within_group']
+ 'tuple_', 'type_coerce', 'union', 'union_all', 'update', 'within_group',
+ 'TableSample', 'tablesample']
from .visitors import Visitable
from .selectable import Alias, Join, Select, Selectable, TableClause, \
CompoundSelect, CTE, FromClause, FromGrouping, Lateral, SelectBase, \
alias, GenerativeSelect, subquery, HasCTE, HasPrefixes, HasSuffixes, \
- lateral, Exists, ScalarSelect, TextAsFrom
+ lateral, Exists, ScalarSelect, TextAsFrom, TableSample, tablesample
from .dml import Insert, Update, Delete, UpdateBase, ValuesBase
return selectable.lateral(name=name)
+def tablesample(selectable, sampling, name=None, seed=None):
+ """Return a :class:`.TableSample` object.
+
+ :class:`.TableSample` is an :class:`.Alias` subclass that represents
+ a table with the TABLESAMPLE clause applied to it.
+ :func:`~.expression.tablesample`
+ is also available from the :class:`.FromClause` class via the
+ :meth:`.FromClause.tablesample` method.
+
+ The TABLESAMPLE clause allows selecting a randomly selected approximate
+ percentage of rows from a table. It supports multiple sampling methods,
+ most commonly BERNOULLI and SYSTEM.
+
+ e.g.::
+
+ from sqlalchemy import func
+
+ selectable = people.tablesample(
+ func.bernoulli(1),
+ name='alias',
+ seed=func.random())
+ stmt = select([selectable.c.people_id])
+
+ Assuming ``people`` with a column ``people_id``, the above
+ statement would render as::
+
+ SELECT alias.people_id FROM
+ people AS alias TABLESAMPLE bernoulli(:bernoulli_1)
+ REPEATABLE (random())
+
+ .. versionadded:: 1.1
+
+ :param sampling: a ``float`` percentage between 0 and 100 or
+ :class:`.functions.Function`.
+
+ :param name: optional alias name
+
+ :param seed: any real-valued SQL expression. When specified, the
+ REPEATABLE sub-clause is also rendered.
+
+ """
+ return _interpret_as_from(selectable).tablesample(
+ sampling, name=name, seed=seed)
+
+
class Selectable(ClauseElement):
"""mark a class as being selectable"""
__visit_name__ = 'selectable'
"""
return Lateral(self, name)
+ def tablesample(self, sampling, name=None, seed=None):
+ """Return a TABLESAMPLE alias of this :class:`.FromClause`.
+
+ The return value is the :class:`.TableSample` construct also
+ provided by the top-level :func:`~.expression.tablesample` function.
+
+ .. versionadded:: 1.1
+
+ .. seealso::
+
+ :func:`~.expression.tablesample` - usage guidelines and parameters
+
+ """
+ return TableSample(self, sampling, name, seed)
+
def is_derived_from(self, fromclause):
"""Return True if this FromClause is 'derived' from the given
FromClause.
__visit_name__ = 'lateral'
+class TableSample(Alias):
+ """Represent a TABLESAMPLE clause.
+
+ This object is constructed from the :func:`~.expression.tablesample` module
+ level function as well as the :meth:`.FromClause.tablesample` method available
+ on all :class:`.FromClause` subclasses.
+
+ .. versionadded:: 1.1
+
+ .. seealso::
+
+ :func:`~.expression.tablesample`
+
+ """
+
+ __visit_name__ = 'tablesample'
+
+ def __init__(self, selectable, sampling,
+ name=None,
+ seed=None):
+ self.sampling = sampling
+ self.seed = seed
+ super(TableSample, self).__init__(selectable, name=name)
+
+ @util.dependencies("sqlalchemy.sql.functions")
+ def _get_method(self, functions):
+ if isinstance(self.sampling, functions.Function):
+ return self.sampling
+ else:
+ return functions.func.system(self.sampling)
+
+
class CTE(Generative, HasSuffixes, Alias):
"""Represent a Common Table Expression.
--- /dev/null
+from sqlalchemy.testing import fixtures
+from sqlalchemy.testing import AssertsCompiledSQL, assert_raises_message
+from sqlalchemy.sql import select, func, text
+from sqlalchemy.engine import default
+from sqlalchemy import exc
+from sqlalchemy import Table, Integer, String, Column
+from sqlalchemy import tablesample
+
+
+class TableSampleTest(fixtures.TablesTest, AssertsCompiledSQL):
+ __dialect__ = default.DefaultDialect(supports_native_boolean=True)
+
+ run_setup_bind = None
+
+ run_create_tables = None
+
+ @classmethod
+ def define_tables(cls, metadata):
+ Table('people', metadata,
+ Column('people_id', Integer, primary_key=True),
+ Column('age', Integer),
+ Column('name', String(30)))
+
+ def test_standalone(self):
+ table1 = self.tables.people
+
+ # no special alias handling even though clause is not in the
+ # context of a FROM clause
+ self.assert_compile(
+ tablesample(table1, 1, name='alias'),
+ 'people AS alias TABLESAMPLE system(:system_1)'
+ )
+
+ self.assert_compile(
+ table1.tablesample(1, name='alias'),
+ 'people AS alias TABLESAMPLE system(:system_1)'
+ )
+
+ self.assert_compile(
+ tablesample(table1, func.bernoulli(1), name='alias',
+ seed=func.random()),
+ 'people AS alias TABLESAMPLE bernoulli(:bernoulli_1) '
+ 'REPEATABLE (random())'
+ )
+
+ def test_select_from(self):
+ table1 = self.tables.people
+
+ self.assert_compile(
+ select([table1.tablesample(text('1'), name='alias').c.people_id]),
+ 'SELECT alias.people_id FROM '
+ 'people AS alias TABLESAMPLE system(1)'
+ )
+
projects / thirdparty / sqlalchemy / sqlalchemy.git / commitdiff
