pyspark.sql.functions.array_prepend#

pyspark.sql.functions.array_prepend(col, value)[source]#

Array function: Returns an array containing the given element as the first element and the rest of the elements from the original array.

Added in version 3.5.0.

Parameters:

colColumn or str: name of column containing array. A column that evaluates to an array.
value: a literal value, or a Column expression. A column of the same type as the array elements.

Returns:

Column: an array with the given value prepended. Returns a column that evaluates to an array.

See also

pyspark.sql.functions.array_append()
pyspark.sql.functions.array_insert()

Examples

Example 1: Prepending a column value to an array column

>>> from pyspark.sql import Row, functions as sf
>>> df = spark.createDataFrame([Row(c1=["b", "a", "c"], c2="c")])
>>> df.select(sf.array_prepend(df.c1, df.c2)).show()
+---------------------+
|array_prepend(c1, c2)|
+---------------------+
|         [c, b, a, c]|
+---------------------+

Example 2: Prepending a numeric value to an array column

>>> from pyspark.sql import functions as sf
>>> df = spark.createDataFrame([([1, 2, 3],)], ['data'])
>>> df.select(sf.array_prepend(df.data, 4)).show()
+----------------------+
|array_prepend(data, 4)|
+----------------------+
|          [4, 1, 2, 3]|
+----------------------+

Example 3: Prepending a null value to an array column

>>> from pyspark.sql import functions as sf
>>> df = spark.createDataFrame([([1, 2, 3],)], ['data'])
>>> df.select(sf.array_prepend(df.data, None)).show()
+-------------------------+
|array_prepend(data, NULL)|
+-------------------------+
|          [NULL, 1, 2, 3]|
+-------------------------+

Example 4: Prepending a value to a NULL array column

>>> from pyspark.sql import functions as sf
>>> from pyspark.sql.types import ArrayType, IntegerType, StructType, StructField
>>> schema = StructType([
...   StructField("data", ArrayType(IntegerType()), True)
... ])
>>> df = spark.createDataFrame([(None,)], schema=schema)
>>> df.select(sf.array_prepend(df.data, 4)).show()
+----------------------+
|array_prepend(data, 4)|
+----------------------+
|                  NULL|
+----------------------+

Example 5: Prepending a value to an empty array

>>> from pyspark.sql import functions as sf
>>> from pyspark.sql.types import ArrayType, IntegerType, StructType, StructField
>>> schema = StructType([
...   StructField("data", ArrayType(IntegerType()), True)
... ])
>>> df = spark.createDataFrame([([],)], schema=schema)
>>> df.select(sf.array_prepend(df.data, 1)).show()
+----------------------+
|array_prepend(data, 1)|
+----------------------+
|                   [1]|
+----------------------+