Skip to content

Functions Reference

Source code in beacon_api/query/functions.py 
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
class Functions:
    @staticmethod
    def concat(args: List[Union[str, Select]], alias: str) -> SelectFunction:
        """
        Constructs a CONCAT function, concatenating the selected columns or arguments.
        Args:
            args (list[str  |  Select]): List of column names (str) or Select objects to concatenate.
            alias (str): Alias name for the resulting select expression.
        """

        select_args = []
        for arg in args:
            if isinstance(arg, str):
                select_args.append(SelectColumn(column=arg))
            elif isinstance(arg, Select):
                select_args.append(arg)
        return SelectFunction("concat", args=select_args, alias=alias)

    @staticmethod
    def coalesce(args: List[Union[str, Select]], alias: str) -> SelectFunction:
        """
        Constructs a COALESCE function, returning the first non-null value from the selected columns or arguments.
        Args:
            args (list[str  |  Select]): List of column names (str) or Select objects to coalesce.
            alias (str): Alias name for the resulting select expression.

        Returns:
            SelectFunction: SelectFunction representing the COALESCE operation.
        """
        select_args = []
        for arg in args:
            if isinstance(arg, str):
                select_args.append(SelectColumn(column=arg))
            elif isinstance(arg, Select):
                select_args.append(arg)
        return SelectFunction("coalesce", args=select_args, alias=alias)

    @staticmethod
    def try_cast_to_type(arg: Union[str, Select], to_type: DTypeLike, alias: str) -> SelectFunction:
            """
            Attempts to cast the input column or argument to the specified data type.
            Args:
                arg: Column name (str) or Select object to cast.
                to_type: Target data type (compatible with numpy dtype). Eg. np.int64, np.float64, np.datetime64, np.str_
                alias: Alias name for the resulting select expression.
            Returns:
                SelectFunction representing the cast operation.
            """
            dtype = np.dtype(to_type)  # normalize everything into a np.dtype
            arrow_type = None
            if np.issubdtype(dtype, np.integer):
                print("This is an integer dtype:", dtype)
                arrow_type = "Int64"
            elif np.issubdtype(dtype, np.floating):
                arrow_type = "Float64"
            elif np.issubdtype(dtype, np.datetime64):
                arrow_type = 'Timestamp(Nanosecond, None)'
            elif np.issubdtype(dtype, np.str_):
                arrow_type = 'Utf8'
            else:
                raise ValueError(f"Unsupported type for cast_to_type: {to_type}")

            if isinstance(arg, str):
                arg = SelectColumn(column=arg)
                return SelectFunction("try_arrow_cast", args=[arg, SelectLiteral(value=arrow_type)], alias=alias)
            elif isinstance(arg, Select):
                return SelectFunction("try_arrow_cast", args=[arg, SelectLiteral(value=arrow_type)], alias=alias)

    @staticmethod
    def cast_byte_to_char(arg: Union[str, Select], alias: str) -> SelectFunction:
        """Maps byte values to char.

        Args:
            arg (str | Select): column name (str) or Select object containing the byte value.
            alias (str): Alias name for the resulting select expression/column.

        Returns:
            SelectFunction: SelectFunction representing the cast operation.
        """
        if isinstance(arg, str):
            arg = SelectColumn(column=arg)
        return SelectFunction("cast_int8_as_char", args=[arg], alias=alias)

    @staticmethod
    def map_wod_quality_flag_to_sdn_scheme(arg: Union[str, Select], alias: str) -> SelectFunction:
        """Maps WOD quality flags to the SDN scheme.

        Args:
            arg (str | Select): column name (str) or Select object containing the WOD quality flag.
            alias (str): Alias name for the resulting select expression/column.

        Returns:
            SelectFunction: SelectFunction representing the mapping operation.
        """
        if isinstance(arg, str):
            arg = SelectColumn(column=arg)
        return SelectFunction("map_wod_quality_flag", args=[arg], alias=alias)

    @staticmethod
    def map_pressure_to_depth(arg: Union[str, Select], latitude_column: Union[str, Select], alias: str) -> SelectFunction:
        """Maps pressure values to depth based on latitude using teos-10.

        Args:
            arg (str | Select): column name (str) or Select object containing the pressure value.
            latitude_column (str | Select): column name (str) or Select object containing the latitude value.
            alias (str): Alias name for the resulting select expression/column.

        Returns:
            SelectFunction: SelectFunction representing the pressure-to-depth mapping operation.
        """
        if isinstance(arg, str):
            arg = SelectColumn(column=arg)
        if isinstance(latitude_column, str):
            latitude_column = SelectColumn(column=latitude_column)
        return SelectFunction("pressure_to_depth_teos_10", args=[arg, latitude_column], alias=alias)

cast_byte_to_char(arg, alias) staticmethod

Maps byte values to char.

Args: arg (str | Select): column name (str) or Select object containing the byte value. alias (str): Alias name for the resulting select expression/column.

Returns: SelectFunction: SelectFunction representing the cast operation.

Source code in beacon_api/query/functions.py 
86
87
88
89
90
91
92
93
94
95
96
97
98
99
@staticmethod
def cast_byte_to_char(arg: Union[str, Select], alias: str) -> SelectFunction:
    """Maps byte values to char.

    Args:
        arg (str | Select): column name (str) or Select object containing the byte value.
        alias (str): Alias name for the resulting select expression/column.

    Returns:
        SelectFunction: SelectFunction representing the cast operation.
    """
    if isinstance(arg, str):
        arg = SelectColumn(column=arg)
    return SelectFunction("cast_int8_as_char", args=[arg], alias=alias)

coalesce(args, alias) staticmethod

Constructs a COALESCE function, returning the first non-null value from the selected columns or arguments. Args: args (list[str | Select]): List of column names (str) or Select objects to coalesce. alias (str): Alias name for the resulting select expression.

Returns: SelectFunction: SelectFunction representing the COALESCE operation.

Source code in beacon_api/query/functions.py 
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
@staticmethod
def coalesce(args: List[Union[str, Select]], alias: str) -> SelectFunction:
    """
    Constructs a COALESCE function, returning the first non-null value from the selected columns or arguments.
    Args:
        args (list[str  |  Select]): List of column names (str) or Select objects to coalesce.
        alias (str): Alias name for the resulting select expression.

    Returns:
        SelectFunction: SelectFunction representing the COALESCE operation.
    """
    select_args = []
    for arg in args:
        if isinstance(arg, str):
            select_args.append(SelectColumn(column=arg))
        elif isinstance(arg, Select):
            select_args.append(arg)
    return SelectFunction("coalesce", args=select_args, alias=alias)

concat(args, alias) staticmethod

Constructs a CONCAT function, concatenating the selected columns or arguments. Args: args (list[str | Select]): List of column names (str) or Select objects to concatenate. alias (str): Alias name for the resulting select expression.

Source code in beacon_api/query/functions.py 
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
@staticmethod
def concat(args: List[Union[str, Select]], alias: str) -> SelectFunction:
    """
    Constructs a CONCAT function, concatenating the selected columns or arguments.
    Args:
        args (list[str  |  Select]): List of column names (str) or Select objects to concatenate.
        alias (str): Alias name for the resulting select expression.
    """

    select_args = []
    for arg in args:
        if isinstance(arg, str):
            select_args.append(SelectColumn(column=arg))
        elif isinstance(arg, Select):
            select_args.append(arg)
    return SelectFunction("concat", args=select_args, alias=alias)

map_pressure_to_depth(arg, latitude_column, alias) staticmethod

Maps pressure values to depth based on latitude using teos-10.

Args: arg (str | Select): column name (str) or Select object containing the pressure value. latitude_column (str | Select): column name (str) or Select object containing the latitude value. alias (str): Alias name for the resulting select expression/column.

Returns: SelectFunction: SelectFunction representing the pressure-to-depth mapping operation.

Source code in beacon_api/query/functions.py 
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
@staticmethod
def map_pressure_to_depth(arg: Union[str, Select], latitude_column: Union[str, Select], alias: str) -> SelectFunction:
    """Maps pressure values to depth based on latitude using teos-10.

    Args:
        arg (str | Select): column name (str) or Select object containing the pressure value.
        latitude_column (str | Select): column name (str) or Select object containing the latitude value.
        alias (str): Alias name for the resulting select expression/column.

    Returns:
        SelectFunction: SelectFunction representing the pressure-to-depth mapping operation.
    """
    if isinstance(arg, str):
        arg = SelectColumn(column=arg)
    if isinstance(latitude_column, str):
        latitude_column = SelectColumn(column=latitude_column)
    return SelectFunction("pressure_to_depth_teos_10", args=[arg, latitude_column], alias=alias)

map_wod_quality_flag_to_sdn_scheme(arg, alias) staticmethod

Maps WOD quality flags to the SDN scheme.

Args: arg (str | Select): column name (str) or Select object containing the WOD quality flag. alias (str): Alias name for the resulting select expression/column.

Returns: SelectFunction: SelectFunction representing the mapping operation.

Source code in beacon_api/query/functions.py 
101
102
103
104
105
106
107
108
109
110
111
112
113
114
@staticmethod
def map_wod_quality_flag_to_sdn_scheme(arg: Union[str, Select], alias: str) -> SelectFunction:
    """Maps WOD quality flags to the SDN scheme.

    Args:
        arg (str | Select): column name (str) or Select object containing the WOD quality flag.
        alias (str): Alias name for the resulting select expression/column.

    Returns:
        SelectFunction: SelectFunction representing the mapping operation.
    """
    if isinstance(arg, str):
        arg = SelectColumn(column=arg)
    return SelectFunction("map_wod_quality_flag", args=[arg], alias=alias)

try_cast_to_type(arg, to_type, alias) staticmethod

Attempts to cast the input column or argument to the specified data type. Args: arg: Column name (str) or Select object to cast. to_type: Target data type (compatible with numpy dtype). Eg. np.int64, np.float64, np.datetime64, np.str_ alias: Alias name for the resulting select expression. Returns: SelectFunction representing the cast operation.

Source code in beacon_api/query/functions.py 
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
@staticmethod
def try_cast_to_type(arg: Union[str, Select], to_type: DTypeLike, alias: str) -> SelectFunction:
        """
        Attempts to cast the input column or argument to the specified data type.
        Args:
            arg: Column name (str) or Select object to cast.
            to_type: Target data type (compatible with numpy dtype). Eg. np.int64, np.float64, np.datetime64, np.str_
            alias: Alias name for the resulting select expression.
        Returns:
            SelectFunction representing the cast operation.
        """
        dtype = np.dtype(to_type)  # normalize everything into a np.dtype
        arrow_type = None
        if np.issubdtype(dtype, np.integer):
            print("This is an integer dtype:", dtype)
            arrow_type = "Int64"
        elif np.issubdtype(dtype, np.floating):
            arrow_type = "Float64"
        elif np.issubdtype(dtype, np.datetime64):
            arrow_type = 'Timestamp(Nanosecond, None)'
        elif np.issubdtype(dtype, np.str_):
            arrow_type = 'Utf8'
        else:
            raise ValueError(f"Unsupported type for cast_to_type: {to_type}")

        if isinstance(arg, str):
            arg = SelectColumn(column=arg)
            return SelectFunction("try_arrow_cast", args=[arg, SelectLiteral(value=arrow_type)], alias=alias)
        elif isinstance(arg, Select):
            return SelectFunction("try_arrow_cast", args=[arg, SelectLiteral(value=arrow_type)], alias=alias)