Skip to content

Schema

Store column names and corresponding data types for a Table or Row.

Parameters:

Name Type Description Default
schema dict[str, ColumnType]

Map from column names to data types.

 required

Examples:

>>> from safeds.data.tabular.typing import Integer, Schema, String
>>> schema = Schema({"A": Integer(), "B": String()})
Source code in src/safeds/data/tabular/typing/_schema.py 
 14
 15
 16
 17
 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
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
@dataclass
class Schema:
    """
    Store column names and corresponding data types for a `Table` or `Row`.

    Parameters
    ----------
    schema : dict[str, ColumnType]
        Map from column names to data types.

    Examples
    --------
    >>> from safeds.data.tabular.typing import Integer, Schema, String
    >>> schema = Schema({"A": Integer(), "B": String()})
    """

    _schema: dict[str, ColumnType]

    # ------------------------------------------------------------------------------------------------------------------
    # Creation
    # ------------------------------------------------------------------------------------------------------------------

    @staticmethod
    def _from_pandas_dataframe(dataframe: pd.DataFrame) -> Schema:
        """
        Create a schema from a `pandas.DataFrame`.

        Parameters
        ----------
        dataframe : pd.DataFrame
            The dataframe.

        Returns
        -------
        schema : Schema
            The schema.
        """
        names = dataframe.columns
        # noinspection PyProtectedMember
        types = []
        for col in dataframe:
            types.append(ColumnType._data_type(dataframe[col]))

        return Schema(dict(zip(names, types, strict=True)))

    # ------------------------------------------------------------------------------------------------------------------
    # Dunder methods
    # ------------------------------------------------------------------------------------------------------------------

    def __init__(self, schema: dict[str, ColumnType]):
        self._schema = dict(schema)  # Defensive copy

    def __hash__(self) -> int:
        """
        Return a hash value for the schema.

        Returns
        -------
        hash : int
            The hash value.

        Examples
        --------
        >>> from safeds.data.tabular.typing import Integer, Schema, String
        >>> schema = Schema({"A": Integer(), "B": String()})
        >>> hash_value = hash(schema)
        """
        column_names = self._schema.keys()
        column_types = map(repr, self._schema.values())
        return hash(tuple(zip(column_names, column_types, strict=True)))

    def __repr__(self) -> str:
        """
        Return an unambiguous string representation of this row.

        Returns
        -------
        representation : str
            The string representation.

        Examples
        --------
        >>> from safeds.data.tabular.typing import Integer, Schema, String
        >>> schema = Schema({"A": Integer()})
        >>> repr(schema)
        "Schema({'A': Integer})"
        """
        return f"Schema({self!s})"

    def __str__(self) -> str:
        """
        Return a user-friendly string representation of the schema.

        Returns
        -------
        string : str
            The string representation.

        Examples
        --------
        >>> from safeds.data.tabular.typing import Integer, Schema, String
        >>> schema = Schema({"A": Integer()})
        >>> str(schema)
        "{'A': Integer}"
        """
        match len(self._schema):
            case 0:
                return "{}"
            case 1:
                return str(self._schema)
            case _:
                lines = (f"    {name!r}: {type_}" for name, type_ in self._schema.items())
                joined = ",\n".join(lines)
                return f"{{\n{joined}\n}}"

    @property
    def column_names(self) -> list[str]:
        """
        Return a list of all column names saved in this schema.

        Returns
        -------
        column_names : list[str]
            The column names.

        Examples
        --------
        >>> from safeds.data.tabular.typing import Integer, Schema, String
        >>> schema = Schema({"A": Integer(), "B": String()})
        >>> schema.column_names
        ['A', 'B']
        """
        return list(self._schema.keys())

    def has_column(self, column_name: str) -> bool:
        """
        Return whether the schema contains a given column.

        Parameters
        ----------
        column_name : str
            The name of the column.

        Returns
        -------
        contains : bool
            True if the schema contains the column.

        Examples
        --------
        >>> from safeds.data.tabular.typing import Integer, Schema, String
        >>> schema = Schema({"A": Integer(), "B": String()})
        >>> schema.has_column("A")
        True

        >>> schema.has_column("C")
        False
        """
        return column_name in self._schema

    def get_column_type(self, column_name: str) -> ColumnType:
        """
        Return the type of the given column.

        Parameters
        ----------
        column_name : str
            The name of the column.

        Returns
        -------
        type : ColumnType
            The type of the column.

        Raises
        ------
        UnknownColumnNameError
            If the specified column name does not exist.

        Examples
        --------
        >>> from safeds.data.tabular.typing import Integer, Schema, String
        >>> schema = Schema({"A": Integer(), "B": String()})
        >>> schema.get_column_type("A")
        Integer
        """
        if not self.has_column(column_name):
            raise UnknownColumnNameError([column_name])
        return self._schema[column_name]

    # ------------------------------------------------------------------------------------------------------------------
    # Conversion
    # ------------------------------------------------------------------------------------------------------------------

    def to_dict(self) -> dict[str, ColumnType]:
        """
        Return a dictionary that maps column names to column types.

        Returns
        -------
        data : dict[str, ColumnType]
            Dictionary representation of the schema.

        Examples
        --------
        >>> from safeds.data.tabular.typing import Integer, Schema, String
        >>> schema = Schema({"A": Integer(), "B": String()})
        >>> schema.to_dict()
        {'A': Integer, 'B': String}
        """
        return dict(self._schema)  # defensive copy

    @staticmethod
    def merge_multiple_schemas(schemas: list[Schema]) -> Schema:
        """
        Merge multiple schemas into one.

        For each type missmatch the new schema will have the least common supertype.

        The type hierarchy is as follows:
        * Anything
            * RealNumber
                * Integer
            * Boolean
            * String

        Parameters
        ----------
        schemas : list[Schema]
            the list of schemas you want to merge

        Returns
        -------
        schema : Schema
            the new merged schema

        Raises
        ------
        UnknownColumnNameError
            if not all schemas have the same column names
        """
        schema_dict = schemas[0]._schema
        missing_col_names = set()
        for schema in schemas:
            missing_col_names.update(set(schema.column_names) - set(schema_dict.keys()))
        if len(missing_col_names) > 0:
            raise UnknownColumnNameError(list(missing_col_names))
        for schema in schemas:
            if schema_dict != schema._schema:
                for col_name in schema_dict:
                    nullable = False
                    if schema_dict[col_name].is_nullable() or schema.get_column_type(col_name).is_nullable():
                        nullable = True
                    if isinstance(schema_dict[col_name], type(schema.get_column_type(col_name))):
                        if schema.get_column_type(col_name).is_nullable() and not schema_dict[col_name].is_nullable():
                            schema_dict[col_name] = type(schema.get_column_type(col_name))(nullable)
                        continue
                    if (
                        isinstance(schema_dict[col_name], RealNumber)
                        and isinstance(schema.get_column_type(col_name), Integer)
                    ) or (
                        isinstance(schema_dict[col_name], Integer)
                        and isinstance(schema.get_column_type(col_name), RealNumber)
                    ):
                        schema_dict[col_name] = RealNumber(nullable)
                        continue
                    if isinstance(schema_dict[col_name], Nothing):
                        schema_dict[col_name] = type(schema.get_column_type(col_name))(nullable)
                        continue
                    if isinstance(schema.get_column_type(col_name), Nothing):
                        schema_dict[col_name] = type(schema_dict[col_name])(nullable)
                        continue
                    schema_dict[col_name] = Anything(nullable)
        return Schema(schema_dict)

    # ------------------------------------------------------------------------------------------------------------------
    # IPython Integration
    # ------------------------------------------------------------------------------------------------------------------

    def _repr_markdown_(self) -> str:
        """
        Return a Markdown representation of the schema.

        Returns
        -------
        markdown : str
            The Markdown representation.
        """
        if len(self._schema) == 0:
            return "Empty Schema"

        lines = (f"| {name} | {type_} |" for name, type_ in self._schema.items())
        joined = "\n".join(lines)
        return f"| Column Name | Column Type |\n| --- | --- |\n{joined}"

column_names: list[str] property

Return a list of all column names saved in this schema.

Returns:

Name Type Description
column_names list[str]

The column names.

Examples:

>>> from safeds.data.tabular.typing import Integer, Schema, String
>>> schema = Schema({"A": Integer(), "B": String()})
>>> schema.column_names
['A', 'B']

__hash__()

Return a hash value for the schema.

Returns:

Name Type Description
hash int

The hash value.

Examples:

>>> from safeds.data.tabular.typing import Integer, Schema, String
>>> schema = Schema({"A": Integer(), "B": String()})
>>> hash_value = hash(schema)
Source code in src/safeds/data/tabular/typing/_schema.py 
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
def __hash__(self) -> int:
    """
    Return a hash value for the schema.

    Returns
    -------
    hash : int
        The hash value.

    Examples
    --------
    >>> from safeds.data.tabular.typing import Integer, Schema, String
    >>> schema = Schema({"A": Integer(), "B": String()})
    >>> hash_value = hash(schema)
    """
    column_names = self._schema.keys()
    column_types = map(repr, self._schema.values())
    return hash(tuple(zip(column_names, column_types, strict=True)))

__init__(schema)

Source code in src/safeds/data/tabular/typing/_schema.py 
63
64
def __init__(self, schema: dict[str, ColumnType]):
    self._schema = dict(schema)  # Defensive copy

__repr__()

Return an unambiguous string representation of this row.

Returns:

Name Type Description
representation str

The string representation.

Examples:

>>> from safeds.data.tabular.typing import Integer, Schema, String
>>> schema = Schema({"A": Integer()})
>>> repr(schema)
"Schema({'A': Integer})"
Source code in src/safeds/data/tabular/typing/_schema.py 
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
def __repr__(self) -> str:
    """
    Return an unambiguous string representation of this row.

    Returns
    -------
    representation : str
        The string representation.

    Examples
    --------
    >>> from safeds.data.tabular.typing import Integer, Schema, String
    >>> schema = Schema({"A": Integer()})
    >>> repr(schema)
    "Schema({'A': Integer})"
    """
    return f"Schema({self!s})"

__str__()

Return a user-friendly string representation of the schema.

Returns:

Name Type Description
string str

The string representation.

Examples:

>>> from safeds.data.tabular.typing import Integer, Schema, String
>>> schema = Schema({"A": Integer()})
>>> str(schema)
"{'A': Integer}"
Source code in src/safeds/data/tabular/typing/_schema.py 
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
def __str__(self) -> str:
    """
    Return a user-friendly string representation of the schema.

    Returns
    -------
    string : str
        The string representation.

    Examples
    --------
    >>> from safeds.data.tabular.typing import Integer, Schema, String
    >>> schema = Schema({"A": Integer()})
    >>> str(schema)
    "{'A': Integer}"
    """
    match len(self._schema):
        case 0:
            return "{}"
        case 1:
            return str(self._schema)
        case _:
            lines = (f"    {name!r}: {type_}" for name, type_ in self._schema.items())
            joined = ",\n".join(lines)
            return f"{{\n{joined}\n}}"

get_column_type(column_name)

Return the type of the given column.

Parameters:

Name Type Description Default
column_name str

The name of the column.

 required

Returns:

Name Type Description
type ColumnType

The type of the column.

Raises:

Type Description
UnknownColumnNameError

If the specified column name does not exist.

Examples:

>>> from safeds.data.tabular.typing import Integer, Schema, String
>>> schema = Schema({"A": Integer(), "B": String()})
>>> schema.get_column_type("A")
Integer
Source code in src/safeds/data/tabular/typing/_schema.py 
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
def get_column_type(self, column_name: str) -> ColumnType:
    """
    Return the type of the given column.

    Parameters
    ----------
    column_name : str
        The name of the column.

    Returns
    -------
    type : ColumnType
        The type of the column.

    Raises
    ------
    UnknownColumnNameError
        If the specified column name does not exist.

    Examples
    --------
    >>> from safeds.data.tabular.typing import Integer, Schema, String
    >>> schema = Schema({"A": Integer(), "B": String()})
    >>> schema.get_column_type("A")
    Integer
    """
    if not self.has_column(column_name):
        raise UnknownColumnNameError([column_name])
    return self._schema[column_name]

has_column(column_name)

Return whether the schema contains a given column.

Parameters:

Name Type Description Default
column_name str

The name of the column.

 required

Returns:

Name Type Description
contains bool

True if the schema contains the column.

Examples:

>>> from safeds.data.tabular.typing import Integer, Schema, String
>>> schema = Schema({"A": Integer(), "B": String()})
>>> schema.has_column("A")
True

>>> schema.has_column("C")
False
Source code in src/safeds/data/tabular/typing/_schema.py 
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
def has_column(self, column_name: str) -> bool:
    """
    Return whether the schema contains a given column.

    Parameters
    ----------
    column_name : str
        The name of the column.

    Returns
    -------
    contains : bool
        True if the schema contains the column.

    Examples
    --------
    >>> from safeds.data.tabular.typing import Integer, Schema, String
    >>> schema = Schema({"A": Integer(), "B": String()})
    >>> schema.has_column("A")
    True

    >>> schema.has_column("C")
    False
    """
    return column_name in self._schema

merge_multiple_schemas(schemas) staticmethod

Merge multiple schemas into one.

For each type missmatch the new schema will have the least common supertype.

The type hierarchy is as follows: * Anything * RealNumber * Integer * Boolean * String

Parameters:

Name Type Description Default
schemas list[Schema]

the list of schemas you want to merge

 required

Returns:

Name Type Description
schema Schema

the new merged schema

Raises:

Type Description
UnknownColumnNameError

if not all schemas have the same column names
Source code in src/safeds/data/tabular/typing/_schema.py 
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
@staticmethod
def merge_multiple_schemas(schemas: list[Schema]) -> Schema:
    """
    Merge multiple schemas into one.

    For each type missmatch the new schema will have the least common supertype.

    The type hierarchy is as follows:
    * Anything
        * RealNumber
            * Integer
        * Boolean
        * String

    Parameters
    ----------
    schemas : list[Schema]
        the list of schemas you want to merge

    Returns
    -------
    schema : Schema
        the new merged schema

    Raises
    ------
    UnknownColumnNameError
        if not all schemas have the same column names
    """
    schema_dict = schemas[0]._schema
    missing_col_names = set()
    for schema in schemas:
        missing_col_names.update(set(schema.column_names) - set(schema_dict.keys()))
    if len(missing_col_names) > 0:
        raise UnknownColumnNameError(list(missing_col_names))
    for schema in schemas:
        if schema_dict != schema._schema:
            for col_name in schema_dict:
                nullable = False
                if schema_dict[col_name].is_nullable() or schema.get_column_type(col_name).is_nullable():
                    nullable = True
                if isinstance(schema_dict[col_name], type(schema.get_column_type(col_name))):
                    if schema.get_column_type(col_name).is_nullable() and not schema_dict[col_name].is_nullable():
                        schema_dict[col_name] = type(schema.get_column_type(col_name))(nullable)
                    continue
                if (
                    isinstance(schema_dict[col_name], RealNumber)
                    and isinstance(schema.get_column_type(col_name), Integer)
                ) or (
                    isinstance(schema_dict[col_name], Integer)
                    and isinstance(schema.get_column_type(col_name), RealNumber)
                ):
                    schema_dict[col_name] = RealNumber(nullable)
                    continue
                if isinstance(schema_dict[col_name], Nothing):
                    schema_dict[col_name] = type(schema.get_column_type(col_name))(nullable)
                    continue
                if isinstance(schema.get_column_type(col_name), Nothing):
                    schema_dict[col_name] = type(schema_dict[col_name])(nullable)
                    continue
                schema_dict[col_name] = Anything(nullable)
    return Schema(schema_dict)

to_dict()

Return a dictionary that maps column names to column types.

Returns:

Name Type Description
data dict[str, ColumnType]

Dictionary representation of the schema.

Examples:

>>> from safeds.data.tabular.typing import Integer, Schema, String
>>> schema = Schema({"A": Integer(), "B": String()})
>>> schema.to_dict()
{'A': Integer, 'B': String}
Source code in src/safeds/data/tabular/typing/_schema.py 
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
def to_dict(self) -> dict[str, ColumnType]:
    """
    Return a dictionary that maps column names to column types.

    Returns
    -------
    data : dict[str, ColumnType]
        Dictionary representation of the schema.

    Examples
    --------
    >>> from safeds.data.tabular.typing import Integer, Schema, String
    >>> schema = Schema({"A": Integer(), "B": String()})
    >>> schema.to_dict()
    {'A': Integer, 'B': String}
    """
    return dict(self._schema)  # defensive copy