wjones127 commented on code in PR #13687:
URL: https://github.com/apache/arrow/pull/13687#discussion_r977763363
##########
docs/source/python/compute.rst:
##########
@@ -370,3 +370,134 @@ our ``even_filter`` with a ``pc.field("nums") > 5``
filter:
:class:`.Dataset` currently can be filtered using :meth:`.Dataset.to_table`
method
passing a ``filter`` argument. See :ref:`py-filter-dataset` in Dataset
documentation.
+
+
+User-Defined Functions
+======================
+
+.. warning::
+ This API is **experimental**.
+
+PyArrow allows defining and registering custom compute functions.
+These functions can then be called from Python as well as C++ (and potentially
+any other implementation wrapping Arrow C++, such as the R ``arrow`` package)
+using their registered function name.
+
+To register a UDF, a function name, function docs, input types and
+output type need to be defined. Using
:func:`pyarrow.compute.register_scalar_function`,
+
+.. code-block:: python
+
+ import numpy as np
+
+ import pyarrow as pa
+ import pyarrow.compute as pc
+
+ function_name = "numpy_gcd"
+ function_docs = {
+ "summary": "Calculates the greatest common divisor",
+ "description":
+ "Given 'x' and 'y' find the greatest number that divides\n"
+ "evenly into both x and y."
+ }
+
+ input_types = {
+ "x" : pa.int64(),
+ "y" : pa.int64()
+ }
+
+ output_type = pa.int64()
+
+ def to_np(val):
+ if isinstance(val, pa.Scalar):
+ return val.as_py()
+ else:
+ return np.array(val)
+
+ def gcd_numpy(ctx, x, y):
+ np_x = to_np(x)
+ np_y = to_np(y)
+ return pa.array(np.gcd(np_x, np_y))
+
+ pc.register_scalar_function(gcd_numpy,
+ function_name,
+ function_docs,
+ input_types,
+ output_type)
+
+
+The implementation of a user-defined function always takes first *context*
+parameter (named ``ctx`` in the example above) which is an instance of
+:class:`pyarrow.compute.ScalarUdfContext`.
+This context exposes several useful attributes, particularly a
+:attr:`~pyarrow.compute.ScalarUdfContext.memory_pool` to be used for
+allocations in the context of the user-defined function.
+
+PyArrow UDFs accept input types of both :class:`~pyarrow.Scalar` and
:class:`~pyarrow.Array`,
+and there will always be at least one input of type :class:`~pyarrow.Array`.
+The output should always be a :class:`~pyarrow.Array`.
+
+You can call a user-defined function directly using
:func:`pyarrow.compute.call_function`:
+
+.. code-block:: python
+
+ >>> pc.call_function("numpy_gcd", [pa.scalar(27), pa.scalar(63)])
+ <pyarrow.Int64Scalar: 9>
+ >>> pc.call_function("numpy_gcd", [pa.scalar(27), pa.array([81, 12, 5])])
+ <pyarrow.lib.Int64Array object at 0x7fcfa0e7b100>
+ [
+ 27,
+ 3,
+ 1
+ ]
+
+Working with Datasets
+---------------------
+
+More generally, user-defined functions are usable everywhere a compute function
+can be referred by its name. For example, they can be called on a dataset's
+column using :meth:`Expression._call`.
+
+Consider an instance where the data is in a table and we want to compute
+the GCD of one column with the scalar value 30. We will be re-using the
+"numpy_gcd" user-defined function that was created above:
+
+.. code-block:: python
+
+ >>> import pyarrow.dataset as ds
+ >>> sample_data = {'category': ['A', 'B', 'C', 'D'], 'value': [90, 630,
1827, 2709]}
+ >>> data_table = pa.Table.from_pydict(sample_data)
+ >>> dataset = ds.dataset(data_table)
+ >>> func_args = [pc.scalar(30), ds.field("value")]
+ >>> dataset.to_table(
+ ... columns={
+ ... 'gcd_value': ds.field('')._call("numpy_gcd", func_args),
+ ... 'value': ds.field('value'),
+ ... 'category': ds.field('category')
+ ... })
+ pyarrow.Table
+ gcd_value: int64
+ value: int64
+ category: string
+ ----
+ gcd_value: [[30,30,3,3]]
+ value: [[90,630,1827,2709]]
+ category: [["A","B","C","D"]]
+
+Note that ``ds.field('')_call(...)`` returns a
:func:`pyarrow.compute.Expression`.
+The arguments passed to this function call are expressions, not scalar values
+(notice the difference between :func:`pyarrow.scalar` and
:func:`pyarrow.compute.scalar`,
+the latter produces an expression).
+This expression is evaluated when the projection operator executes it.
Review Comment:
I don't think this sentence says anything useful, at least in this example.
There's no ambiguity on the Python side of when this would execute.
```suggestion
```
##########
docs/source/python/compute.rst:
##########
@@ -370,3 +370,134 @@ our ``even_filter`` with a ``pc.field("nums") > 5``
filter:
:class:`.Dataset` currently can be filtered using :meth:`.Dataset.to_table`
method
passing a ``filter`` argument. See :ref:`py-filter-dataset` in Dataset
documentation.
+
+
+User-Defined Functions
+======================
+
+.. warning::
+ This API is **experimental**.
+
+PyArrow allows defining and registering custom compute functions.
+These functions can then be called from Python as well as C++ (and potentially
+any other implementation wrapping Arrow C++, such as the R ``arrow`` package)
+using their registered function name.
+
+To register a UDF, a function name, function docs, input types and
+output type need to be defined. Using
:func:`pyarrow.compute.register_scalar_function`,
+
+.. code-block:: python
+
+ import numpy as np
+
+ import pyarrow as pa
+ import pyarrow.compute as pc
+
+ function_name = "numpy_gcd"
+ function_docs = {
+ "summary": "Calculates the greatest common divisor",
+ "description":
+ "Given 'x' and 'y' find the greatest number that divides\n"
+ "evenly into both x and y."
+ }
+
+ input_types = {
+ "x" : pa.int64(),
+ "y" : pa.int64()
+ }
+
+ output_type = pa.int64()
+
+ def to_np(val):
+ if isinstance(val, pa.Scalar):
+ return val.as_py()
+ else:
+ return np.array(val)
+
+ def gcd_numpy(ctx, x, y):
+ np_x = to_np(x)
+ np_y = to_np(y)
+ return pa.array(np.gcd(np_x, np_y))
+
+ pc.register_scalar_function(gcd_numpy,
+ function_name,
+ function_docs,
+ input_types,
+ output_type)
+
+
+The implementation of a user-defined function always takes first *context*
+parameter (named ``ctx`` in the example above) which is an instance of
+:class:`pyarrow.compute.ScalarUdfContext`.
+This context exposes several useful attributes, particularly a
+:attr:`~pyarrow.compute.ScalarUdfContext.memory_pool` to be used for
+allocations in the context of the user-defined function.
+
+PyArrow UDFs accept input types of both :class:`~pyarrow.Scalar` and
:class:`~pyarrow.Array`,
+and there will always be at least one input of type :class:`~pyarrow.Array`.
+The output should always be a :class:`~pyarrow.Array`.
+
+You can call a user-defined function directly using
:func:`pyarrow.compute.call_function`:
+
+.. code-block:: python
+
+ >>> pc.call_function("numpy_gcd", [pa.scalar(27), pa.scalar(63)])
+ <pyarrow.Int64Scalar: 9>
+ >>> pc.call_function("numpy_gcd", [pa.scalar(27), pa.array([81, 12, 5])])
+ <pyarrow.lib.Int64Array object at 0x7fcfa0e7b100>
+ [
+ 27,
+ 3,
+ 1
+ ]
+
+Working with Datasets
+---------------------
+
+More generally, user-defined functions are usable everywhere a compute function
+can be referred by its name. For example, they can be called on a dataset's
Review Comment:
```suggestion
can be referred to by its name. For example, they can be called on a
dataset's
```
##########
docs/source/python/compute.rst:
##########
@@ -370,3 +370,134 @@ our ``even_filter`` with a ``pc.field("nums") > 5``
filter:
:class:`.Dataset` currently can be filtered using :meth:`.Dataset.to_table`
method
passing a ``filter`` argument. See :ref:`py-filter-dataset` in Dataset
documentation.
+
+
+User-Defined Functions
+======================
+
+.. warning::
+ This API is **experimental**.
+
+PyArrow allows defining and registering custom compute functions.
+These functions can then be called from Python as well as C++ (and potentially
+any other implementation wrapping Arrow C++, such as the R ``arrow`` package)
+using their registered function name.
+
+To register a UDF, a function name, function docs, input types and
+output type need to be defined. Using
:func:`pyarrow.compute.register_scalar_function`,
+
+.. code-block:: python
+
+ import numpy as np
+
+ import pyarrow as pa
+ import pyarrow.compute as pc
+
+ function_name = "numpy_gcd"
+ function_docs = {
+ "summary": "Calculates the greatest common divisor",
+ "description":
+ "Given 'x' and 'y' find the greatest number that divides\n"
+ "evenly into both x and y."
+ }
+
+ input_types = {
+ "x" : pa.int64(),
+ "y" : pa.int64()
+ }
+
+ output_type = pa.int64()
+
+ def to_np(val):
+ if isinstance(val, pa.Scalar):
+ return val.as_py()
+ else:
+ return np.array(val)
+
+ def gcd_numpy(ctx, x, y):
+ np_x = to_np(x)
+ np_y = to_np(y)
+ return pa.array(np.gcd(np_x, np_y))
+
+ pc.register_scalar_function(gcd_numpy,
+ function_name,
+ function_docs,
+ input_types,
+ output_type)
+
+
+The implementation of a user-defined function always takes first *context*
+parameter (named ``ctx`` in the example above) which is an instance of
+:class:`pyarrow.compute.ScalarUdfContext`.
+This context exposes several useful attributes, particularly a
+:attr:`~pyarrow.compute.ScalarUdfContext.memory_pool` to be used for
+allocations in the context of the user-defined function.
+
+PyArrow UDFs accept input types of both :class:`~pyarrow.Scalar` and
:class:`~pyarrow.Array`,
+and there will always be at least one input of type :class:`~pyarrow.Array`.
+The output should always be a :class:`~pyarrow.Array`.
+
+You can call a user-defined function directly using
:func:`pyarrow.compute.call_function`:
+
+.. code-block:: python
+
+ >>> pc.call_function("numpy_gcd", [pa.scalar(27), pa.scalar(63)])
+ <pyarrow.Int64Scalar: 9>
+ >>> pc.call_function("numpy_gcd", [pa.scalar(27), pa.array([81, 12, 5])])
+ <pyarrow.lib.Int64Array object at 0x7fcfa0e7b100>
+ [
+ 27,
+ 3,
+ 1
+ ]
+
+Working with Datasets
+---------------------
+
+More generally, user-defined functions are usable everywhere a compute function
+can be referred by its name. For example, they can be called on a dataset's
+column using :meth:`Expression._call`.
+
+Consider an instance where the data is in a table and we want to compute
+the GCD of one column with the scalar value 30. We will be re-using the
+"numpy_gcd" user-defined function that was created above:
+
+.. code-block:: python
+
+ >>> import pyarrow.dataset as ds
+ >>> sample_data = {'category': ['A', 'B', 'C', 'D'], 'value': [90, 630,
1827, 2709]}
+ >>> data_table = pa.Table.from_pydict(sample_data)
+ >>> dataset = ds.dataset(data_table)
+ >>> func_args = [pc.scalar(30), ds.field("value")]
+ >>> dataset.to_table(
+ ... columns={
+ ... 'gcd_value': ds.field('')._call("numpy_gcd", func_args),
+ ... 'value': ds.field('value'),
+ ... 'category': ds.field('category')
+ ... })
+ pyarrow.Table
+ gcd_value: int64
+ value: int64
+ category: string
+ ----
+ gcd_value: [[30,30,3,3]]
+ value: [[90,630,1827,2709]]
+ category: [["A","B","C","D"]]
+
+Note that ``ds.field('')_call(...)`` returns a
:func:`pyarrow.compute.Expression`.
+The arguments passed to this function call are expressions, not scalar values
+(notice the difference between :func:`pyarrow.scalar` and
:func:`pyarrow.compute.scalar`,
+the latter produces an expression).
+This expression is evaluated when the projection operator executes it.
+
+Projection Expressions
+^^^^^^^^^^^^^^^^^^^^^^
+In the above example we used an expression to add a new column (``gcd_value``)
Review Comment:
Is this paragraph describing the definition of a **scalar** function? Or is
that different. Either way, I think we want to say that explicitly ("This is
what it means to be a scalar function" / "These requirements are distinct from
the definition of a scalar function".).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
