GeoEco.Datasets.Table.AddField

Table.AddField(name, dataType, length=None, precision=None, isNullable=None, allowSafeCoercions=True, failIfExists=False)

Adds a field to the table.

If the field cannot be added, an appropriate exception will be raised. This can happen for a variety of reasons, which may include:

  • The underlying storage format or programming library used to access it does not support the addition of fields.

  • The table is not empty, and the format or library only allows fields to be added when it is empty.

  • The format or library does not support the requested parameters. For example, it may not support the requested data type.

  • The table is read-only, or the caller does not have sufficient privileges to add fields.

Parameters:

  • name (str) –

    Name of the field to add.

    The name must conform to all rules imposed by the underlying storage format and programming library used to access it. The caller is expected to be aware of these rules and this method attempts to fail if any rule is violated. Certain libraries are designed to automatically modify the caller’s illegal name to a legal name. Where possible, this function overrides that behavior and tries to fail anyway.

    This function treats names as case-insensitive, even if the underlying format and library support case-sensitive names. This behavior should be of little consequence to most callers; this function will pass the name to the library without changing the case. The only callers that will be affected are those who require the ability to create multiple fields with the same name but different case. That scenario is not supported, regardless of whether the format and library may support it.

    Minimum length꞉ 1.

  • dataType (str) –

    Data type of the field to add.

    The underlying storage format and programming library may only support a subset of the possible data types. To test whether a data type is supported, pass the string 't DataType' to TestCapability(), replacing t with the data type you want to test.

    If allowSafeCoercions is True (the default) and the format or library does not support the requested data type but does support an alternative data type that can fully represent the values of the requested data type, the field will be created with that alternative data type. See the allowSafeCoercions parameter for more information.

    Allowed values꞉ 'binary', 'date', 'datetime', 'float32', 'float64', 'int16', 'int32', 'string'.

  • length (int, optional) –

    Length of the field to add.

    The caller is expected to be aware of the appropriate values for this parameter, based on the underlying storage format and programming library used to access it. If this parameter is provided, it will be passed without any validation to the library. Typically, this parameter should only be provided when creating fields that have the 'string' or 'binary' data type.

    Most formats and libraries impose upper limits on the length of string fields. For some of these, MaxStringLength will return the upper limit.

  • precision (int, optional) –

    Precision of the field to add.

    The caller is expected to be aware of the appropriate values for this parameter, based on the underlying storage format and programming library used to access it. If this parameter is provided, it will be passed without any validation to the library. Typically, this parameter should only be provided when creating fields that have the 'float32' or 'float64' data type.

  • isNullable (bool, optional) –

    Indicates whether or not the added field should be nullable.

    The default value of this parameter, None, indicates that the nullability should be decided by the default behavior of the underlying storage format and programming library used to access it. The value True indicates that the library should be instructed to create a nullable field; False indicates that it should be instructed to create a non-nullable field.

    If True or False is provided and the underlying format or library does not support nullable fields, this function attempts recognize the condition and raise an exception. Some libraries will allow nullable fields to be created even though the underlying format does not truly support them. For example, at the time of this writing, OGR did not recognize the concept of nullability and essentially treated all fields as nullable. In situations like this, we try not to rely on the underlying library to decide whether nullability is supported but detect it independently.

  • allowSafeCoercions (bool, optional) –

    If True and the underlying storage format or programming library does not support the requested data type but does support an alternative data type that can fully represent the values of the requested data type, the field will be added with the alternative data type. If False and the requested data type is not supported, an exception will be raised.

    If True is provided, this function will try the following alternative data types in the order listed and use the first one that is supported:

    Requested Data Type

    Alternate Data Types

    date

    datetime

    int16

    int32, float32, float64

    int32

    float64

    float32

    float64

  • failIfExists (bool, optional) –

    If True and a field already exists with the name requested by the caller, an exception will raised. If False and a field already exists with the name requested by the caller, an exception will not be raised as long as that the field has the exact characteristics requested by the caller (data type, length, and so on).

    As noted above, this function treats field names as case-insensitive, even if the underlying storage format or programming library treat them as case-sensitive.