Add TABLESAMPLE clause support.

The TABLESAMPLE clause allows randomly selecting an approximate percentage
of rows from a table. At least DB2, Microsoft SQL Server and recent
Postgresql support this standard clause.

Fixes: #3718
Change-Id: I3fb8b9223e12a57100df30876b461884c58d72fa
Pull-request: https://github.com/zzzeek/sqlalchemy/pull/277

3 files changed, 43 insertions, 0 deletions

diff --git a/doc/build/changelog/changelog_11.rst b/doc/build/changelog/changelog_11.rst
index 7194ac116..534c3993c 100644
--- a/doc/build/changelog/changelog_11.rst
+++ b/doc/build/changelog/changelog_11.rst
@@ -22,6 +22,17 @@
     :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
 
         A new ORM extension :ref:`indexable_toplevel` is added, which allows
diff --git a/doc/build/changelog/migration_11.rst b/doc/build/changelog/migration_11.rst
index 766b06f2e..f6e04225d 100644
--- a/doc/build/changelog/migration_11.rst
+++ b/doc/build/changelog/migration_11.rst
@@ -1150,6 +1150,32 @@ selectable, e.g. lateral correlation::
 
 :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
diff --git a/doc/build/core/selectable.rst b/doc/build/core/selectable.rst
index 3f4d9565e..f2804f9c2 100644
--- a/doc/build/core/selectable.rst
+++ b/doc/build/core/selectable.rst
@@ -33,6 +33,8 @@ elements are themselves :class:`.ColumnElement` subclasses).
 
 .. autofunction:: sqlalchemy.sql.expression.table
 
+.. autofunction:: tablesample
+
 .. autofunction:: union
 
 .. autofunction:: union_all
@@ -91,6 +93,10 @@ elements are themselves :class:`.ColumnElement` subclasses).
    :members:
    :inherited-members:
 
+.. autoclass:: TableSample
+   :members:
+   :inherited-members:
+
 .. autoclass:: TextAsFrom
    :members:
    :inherited-members: