From 42851df7707769bf0bf4db74108699e9f56c5fac Mon Sep 17 00:00:00 2001
From: jonathan vanasco <jonathan@2xlp.com>
Date: Tue, 28 Sep 2021 11:46:53 -0400
Subject: [PATCH] Fixes: #4504

Docstring for EXTRACT

Change-Id: Ie529ceb3551adedf0df873c22e65f8615cd1c9ef
---
 lib/sqlalchemy/sql/elements.py | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

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
-- 
2.47.3