From: jonathan vanasco <jonathan@2xlp.com>
Date: Tue, 28 Sep 2021 15:46:53 +0000 (-0400)
Subject: Fixes: #4504
X-Git-Tag: rel_1_4_26~47^2
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=42851df7707769bf0bf4db74108699e9f56c5fac;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

Fixes: #4504

Docstring for EXTRACT

Change-Id: Ie529ceb3551adedf0df873c22e65f8615cd1c9ef
---

diff --git a/lib/sqlalchemy/sql/elements.py b/lib/sqlalchemy/sql/elements.py
index 58db56a9c9..04565443d9 100644
--- a/lib/sqlalchemy/sql/elements.py
+++ b/lib/sqlalchemy/sql/elements.py
@@ -3272,6 +3272,36 @@ class Extract(ColumnElement):
         as well as ``func.extract`` from the
         :data:`.func` namespace.
 
+        :param field: The field to extract.
+
+        :param expr: A column or Python scalar expression serving as the
+          right side of the ``EXTRACT`` expression.
+
+        E.g.::
+
+            from sqlalchemy import extract
+            from sqlalchemy import table, column
+
+            logged_table = table("user",
+                    column("id"),
+                    column("date_created"),
+            )
+
+            stmt = select(logged_table.c.id).where(
+                extract("YEAR", logged_table.c.date_created) == 2021
+            )
+
+        In the above example, the statement is used to select ids from the
+        database where the ``YEAR`` component matches a specific value.
+
+        Similarly, one can also select an extracted component::
+
+            stmt = select(
+                extract("YEAR", logged_table.c.date_created)
+            ).where(logged_table.c.id == 1)
+
+        The implementation of ``EXTRACT`` may vary across database backends.
+        Users are reminded to consult their database documentation.
         """
         self.type = type_api.INTEGERTYPE
         self.field = field