Class: QgsField

Encapsulate a field in an attribute table or data source.

QgsField stores metadata about an attribute field, including name, type length, and if applicable, precision.

Note

QgsField objects are implicitly shared.

Methods

alias	Returns the alias for the field (the friendly displayed name of the field ), or an empty string if there is no alias.
comment	Returns the field comment
configurationFlags	Returns the Flags for the field (searchable, …).
constraints	Returns constraints which are present for the field.
convertCompatible	Converts the provided variant to a compatible format
defaultValueDefinition	Returns the expression used when calculating the default value for the field.
displayName	Returns the name to use when displaying this field.
displayNameWithAlias	Returns the name to use when displaying this field and adds the alias in parenthesis if it is defined.
displayString	Formats string for display
displayType	Returns the type to use when displaying this field, including the length and precision of the datatype if applicable.
duplicatePolicy	Returns the field's duplicate policy, which indicates how field values should be handled during a duplicate operation.
editorWidgetSetup	Gets the editor widget setup for the field.
friendlyTypeString	Returns a user friendly, translated representation of the field type.
isDateOrTime	Returns if this field is a date and/or time type.
isNumeric	Returns if this field is numeric.
isReadOnly	Returns True if this field is a read-only field.
length	Gets the length of the field.
mergePolicy	Returns the field's merge policy, which indicates how field values should be handled during a merge operation.
metadata	Returns the map of field metadata.
name	Returns the name of the field.
precision	Gets the precision of the field.
setAlias	Sets the alias for the field (the friendly displayed name of the field ).
setComment	Set the field comment
setConfigurationFlags	Sets the Flags for the field (searchable, …).
setConstraints	Sets constraints which are present for the field.
setDefaultValueDefinition	Sets an expression to use when calculating the default value for the field.
setDuplicatePolicy	Sets the field's duplicate policy, which indicates how field values should be handled during a duplicate operation.
setEditorWidgetSetup	Set the editor widget setup for the field.
setLength	Set the field length.
setMergePolicy	Sets the field's merge policy, which indicates how field values should be handled during a merge operation.
setMetadata	Sets the map of field metadata.
setName	Set the field name.
setPrecision	Set the field precision.
setReadOnly	Make field read-only if readOnly is set to true.
setSplitPolicy	Sets the field's split policy, which indicates how field values should be handled during a split operation.
setSubType	If the field is a collection, set its element's type.
setType	Set variant type.
setTypeName	Set the field type.
splitPolicy	Returns the field's split policy, which indicates how field values should be handled during a split operation.
subType	If the field is a collection, gets its element's type.
type	Gets variant type of the field as it will be retrieved from data source
typeName	Gets the field type.

Static Methods

readableConfigurationFlag

Returns the readable and translated value of the configuration flag

class qgis.core.QgsField

Bases: object

__init__(name: str | None = '', type: QMetaType.Type = QMetaType.Type.UnknownType, typeName: str | None = '', len: int = 0, prec: int = 0, comment: str | None = '', subType: QMetaType.Type = QMetaType.Type.UnknownType)

Constructor. Constructs a new QgsField object.

Parameters:

• name (Optional[str] = '') – Field name

• type (QMetaType.Type = QMetaType.Type.UnknownType) – Field variant type, currently supported: String / Int / Double

• typeName (Optional[str] = '') – Field type (e.g., char, varchar, text, int, serial, double). Field types are usually unique to the source and are stored exactly as returned from the data store.

• len (int = 0) – Field length

• prec (int = 0) – Field precision. Usually decimal places but may also be used in conjunction with other fields types (e.g., variable character fields)

• comment (Optional[str] = '') – Comment for the field

• subType (QMetaType.Type = QMetaType.Type.UnknownType) – If the field is a collection, its element’s type. When all the elements don’t need to have the same type, leave this to QVariant.Invalid.

__init__(name: str | None, type: QVariant.Type, typeName: str | None = '', len: int = 0, prec: int = 0, comment: str | None = '', subType: QVariant.Type = QVariant.Invalid)

Constructor. Constructs a new QgsField object.

Parameters:

• name (Optional[str]) – Field name

• type (QVariant.Type) – Field variant type, currently supported: String / Int / Double

• typeName (Optional[str] = '') – Field type (e.g., char, varchar, text, int, serial, double). Field types are usually unique to the source and are stored exactly as returned from the data store.

• len (int = 0) – Field length

• prec (int = 0) – Field precision. Usually decimal places but may also be used in conjunction with other fields types (e.g., variable character fields)

• comment (Optional[str] = '') – Comment for the field

• subType (QVariant.Type = QVariant.Invalid) – If the field is a collection, its element’s type. When all the elements don’t need to have the same type, leave this to QVariant.Invalid.

Deprecated since version 3.38: Use the method with a QMetaType.Type argument instead.

__init__(other: QgsField)

Parameters:

other (QgsField)

alias(self) → str

Returns the alias for the field (the friendly displayed name of the field ), or an empty string if there is no alias.

See also

setAlias()

Return type:

str

comment(self) → str

Returns the field comment

Return type:

str

configurationFlags(self) → Qgis.FieldConfigurationFlags

Returns the Flags for the field (searchable, …).

See also

setConfigurationFlags()

Added in version 3.34.

Return type:

Qgis.FieldConfigurationFlags

constraints(self) → QgsFieldConstraints

Returns constraints which are present for the field.

See also

setConstraints()

Return type:

QgsFieldConstraints

convertCompatible(self, v: Any) → bool

Converts the provided variant to a compatible format

Parameters:

v (Any) – The value to convert

Raises:

ValueError – if the value could not be converted to a compatible format

Return type:

bool

defaultValueDefinition(self) → QgsDefaultValue

Returns the expression used when calculating the default value for the field.

Return type:

QgsDefaultValue

Returns:

expression evaluated when calculating default values for field, or an empty string if no default is set

See also

setDefaultValueDefinition()

displayName(self) → str

Returns the name to use when displaying this field. This will be the field alias if set, otherwise the field name.

See also

name()

See also

alias()

Return type:

str

displayNameWithAlias(self) → str

Returns the name to use when displaying this field and adds the alias in parenthesis if it is defined.

This will be used when working close to the data structure (i.e. building expressions and queries), when the real field name must be shown but the alias is also useful to understand what the field represents.

See also

name()

See also

alias()

Added in version 3.12.

Return type:

str

displayString(self, v: Any) → str

Formats string for display

Parameters:

v (Any)

Return type:

str

displayType(self, showConstraints: bool = False) → str

Returns the type to use when displaying this field, including the length and precision of the datatype if applicable.

This will be used when the full datatype with details has to displayed to the user.

See also

type()

See also

friendlyTypeString()

Added in version 3.14.

Parameters:

showConstraints (bool = False)

Return type:

str

duplicatePolicy(self) → Qgis.FieldDuplicatePolicy

Returns the field’s duplicate policy, which indicates how field values should be handled during a duplicate operation.

See also

setDuplicatePolicy()

Added in version 3.38.

Return type:

Qgis.FieldDuplicatePolicy

editorWidgetSetup(self) → QgsEditorWidgetSetup

Gets the editor widget setup for the field.

Defaults may be set by the provider and can be overridden by manual field configuration.

Return type:

QgsEditorWidgetSetup

Returns:

the value

friendlyTypeString(self) → str

Returns a user friendly, translated representation of the field type.

Unlike displayType(), this method only returns strings representing the field type and does not include length, precision or constraint information.

See also

type()

See also

displayType()

Added in version 3.14.

Return type:

str

isDateOrTime(self) → bool

Returns if this field is a date and/or time type.

Added in version 3.6.

Return type:

bool

isNumeric(self) → bool

Returns if this field is numeric. Any integer or floating point type will return True for this.

Return type:

bool

isReadOnly(self) → bool

Returns True if this field is a read-only field. This is the case for providers which support generated fields for instance.

Added in version 3.18.

Return type:

bool

length(self) → int

Gets the length of the field.

Return type:

int

Returns:

int containing the length of the field

mergePolicy(self) → Qgis.FieldDomainMergePolicy

Returns the field’s merge policy, which indicates how field values should be handled during a merge operation.

See also

setMergePolicy()

Added in version 3.44.

Return type:

Qgis.FieldDomainMergePolicy

metadata(self) → Dict[int, Any]

Returns the map of field metadata.

Map keys should match values from the Qgis.FieldMetadataProperty enum.

See also

setMetadata()

Added in version 3.32.

Return type:

Dict[int, Any]

metadata(self, property: int) → Any

Returns a specific metadata property.

See also

setMetadata()

Added in version 3.32.

Parameters:

property (int)

Return type:

Any

name(self) → str

Returns the name of the field.

See also

setName()

See also

displayName()

Return type:

str

precision(self) → int

Gets the precision of the field. Not all field types have a related precision.

Return type:

int

Returns:

int containing the precision or zero if not applicable to the field type.

static readableConfigurationFlag(flag: Qgis.FieldConfigurationFlag) → str

Returns the readable and translated value of the configuration flag

Added in version 3.16.

Parameters:

flag (Qgis.FieldConfigurationFlag)

Return type:

str

setAlias(self, alias: str | None)

Sets the alias for the field (the friendly displayed name of the field ).

Parameters:

alias (Optional[str]) – field alias, or empty string to remove an existing alias

See also

alias()

setComment(self, comment: str | None)

Set the field comment

Parameters:

comment (Optional[str])

setConfigurationFlags(self, flags: Qgis.FieldConfigurationFlags | Qgis.FieldConfigurationFlag)

Sets the Flags for the field (searchable, …).

See also

configurationFlags()

Added in version 3.34.

Parameters:

flags (Union[Qgis.FieldConfigurationFlags, Qgis.FieldConfigurationFlag])

setConstraints(self, constraints: QgsFieldConstraints)

Sets constraints which are present for the field.

See also

constraints()

Parameters:

constraints (QgsFieldConstraints)

setDefaultValueDefinition(self, defaultValueDefinition: QgsDefaultValue)

Sets an expression to use when calculating the default value for the field.

Parameters:

defaultValueDefinition (QgsDefaultValue) – expression to evaluate when calculating default values for field. Pass a default constructed QgsDefaultValue to reset.

See also

defaultValueDefinition()

setDuplicatePolicy(self, policy: Qgis.FieldDuplicatePolicy)

Sets the field’s duplicate policy, which indicates how field values should be handled during a duplicate operation.

See also

duplicatePolicy()

Added in version 3.38.

Parameters:

policy (Qgis.FieldDuplicatePolicy)

setEditorWidgetSetup(self, v: QgsEditorWidgetSetup)

Set the editor widget setup for the field.

Parameters:

v (QgsEditorWidgetSetup) – The value to set

setLength(self, len: int)

Set the field length.

Parameters:

len (int) – Length of the field

setMergePolicy(self, policy: Qgis.FieldDomainMergePolicy)

Sets the field’s merge policy, which indicates how field values should be handled during a merge operation.

See also

mergePolicy()

Added in version 3.44.

Parameters:

policy (Qgis.FieldDomainMergePolicy)

setMetadata(self, metadata: Dict[int, Any])

Sets the map of field metadata.

Map keys should match values from the Qgis.FieldMetadataProperty enum.

See also

metadata()

Added in version 3.32.

Parameters:

metadata (Dict[int, Any])

setMetadata(self, property: int, value: Any)

Sets a metadata property to value.

See also

metadata()

Added in version 3.32.

Parameters:

• property (int)

• value (Any)

setName(self, name: str | None)

Set the field name.

Parameters:

name (Optional[str]) – Name of the field

setPrecision(self, precision: int)

Set the field precision.

Parameters:

precision (int) – Precision of the field

setReadOnly(self, readOnly: bool)

Make field read-only if readOnly is set to true. This is the case for providers which support generated fields for instance.

Added in version 3.18.

Parameters:

readOnly (bool)

setSplitPolicy(self, policy: Qgis.FieldDomainSplitPolicy)

Sets the field’s split policy, which indicates how field values should be handled during a split operation.

See also

splitPolicy()

Added in version 3.30.

Parameters:

policy (Qgis.FieldDomainSplitPolicy)

setSubType(self, subType: QMetaType.Type)

If the field is a collection, set its element’s type. When all the elements don’t need to have the same type, set this to QVariant.Invalid.

Parameters:

subType (QMetaType.Type)

setSubType(self, subType: QVariant.Type)

If the field is a collection, set its element’s type. When all the elements don’t need to have the same type, set this to QVariant.Invalid.

Deprecated since version 3.38: Use the method with a QMetaType.Type argument instead.

Parameters:

subType (QVariant.Type)

setType(self, type: QMetaType.Type)

Set variant type.

Parameters:

type (QMetaType.Type)

setType(self, type: QVariant.Type)

Set variant type.

Deprecated since version 3.38: Use the method with a QMetaType.Type argument instead.

Parameters:

type (QVariant.Type)

setTypeName(self, typeName: str | None)

Set the field type.

Parameters:

typeName (Optional[str]) – Field type

splitPolicy(self) → Qgis.FieldDomainSplitPolicy

Returns the field’s split policy, which indicates how field values should be handled during a split operation.

See also

setSplitPolicy()

Added in version 3.30.

Return type:

Qgis.FieldDomainSplitPolicy

subType(self) → QMetaType.Type

If the field is a collection, gets its element’s type. When all the elements don’t need to have the same type, this returns QVariant.Invalid.

Return type:

QMetaType.Type

type(self) → QMetaType.Type

Gets variant type of the field as it will be retrieved from data source

Return type:

QMetaType.Type

typeName(self) → str

Gets the field type. Field types vary depending on the data source. Examples are char, int, double, blob, geometry, etc. The type is stored exactly as the data store reports it, with no attempt to standardize the value.

Return type:

str

Returns:

string containing the field type