Fields
#
Quick SummaryFields (or properties) in the schema are the attributes of the node. For example, a User
with 4 fields: age
, name
, username
and created_at
:
Fields are returned from the schema using the Fields
method. For example:
All fields are required by default, and can be set to optional using the Optional
method.
#
TypesThe following types are currently supported by the framework:
- All Go numeric types. Like
int
,uint8
,float64
, etc. bool
string
time.Time
[]byte
(SQL only).JSON
(SQL only).Enum
(SQL only).UUID
(SQL only).Other
(SQL only).
To read more about how each type is mapped to its database-type, go to the Migration section.
#
ID FieldThe id
field is builtin in the schema and does not need declaration. In SQL-based
databases, its type defaults to int
(but can be changed with a codegen option)
and auto-incremented in the database.
In order to configure the id
field to be unique across all tables, use the
WithGlobalUniqueID option when running schema migration.
If a different configuration for the id
field is needed, or the id
value should
be provided on entity creation by the application (e.g. UUID), override the builtin
id
configuration. For example:
If you need to set a custom function to generate IDs, you can use DefaultFunc
to specify a function which will always be ran when the resource is created.
See the related FAQ for more information.
#
Database TypeEach database dialect has its own mapping from Go type to database type. For example,
the MySQL dialect creates float64
fields as double
columns in the database. However,
there is an option to override the default behavior using the SchemaType
method.
#
Go TypeThe default type for fields are the basic Go types. For example, for string fields, the type is string
,
and for time fields, the type is time.Time
. The GoType
method provides an option to override the
default ent type with a custom one.
The custom type must be either a type that is convertible to the Go basic type, or a type that implements the ValueScanner interface.
#
Other FieldOther represents a field that is not a good fit for any of the standard field types. Examples are a Postgres Range type or Geospatial type
#
Default ValuesNon-unique fields support default values using the Default
and UpdateDefault
methods.
You can also specify DefaultFunc
instead to have a custom generator.
SQL-specific expressions like function calls can be added to default value configuration using the
entsql.Annotation
:
In case your DefaultFunc
is also returning an error, it is better to handle it properly using schema-hooks.
See this FAQ for more information.
#
ValidatorsA field validator is a function from type func(T) error
that is defined in the schema
using the Validate
method, and applied on the field value before creating or updating
the entity.
The supported types of field validators are string
and all numeric types.
Here is another example for writing a reusable validator:
#
Built-in ValidatorsThe framework provides a few built-in validators for each type:
Numeric types:
Positive()
Negative()
NonNegative()
Min(i)
- Validate that the given value is > i.Max(i)
- Validate that the given value is < i.Range(i, j)
- Validate that the given value is within the range [i, j].
string
MinLen(i)
MaxLen(i)
Match(regexp.Regexp)
NotEmpty
#
OptionalOptional fields are fields that are not required in the entity creation, and
will be set to nullable fields in the database.
Unlike edges, fields are required by default, and setting them to
optional should be done explicitly using the Optional
method.
#
NillableSometimes you want to be able to distinguish between the zero value of fields
and nil
; for example if the database column contains 0
or NULL
.
The Nillable
option exists exactly for this.
If you have an Optional
field of type T
, setting it to Nillable
will generate
a struct field with type *T
. Hence, if the database returns NULL
for this field,
the struct field will be nil
. Otherwise, it will contains a pointer to the actual data.
For example, given this schema:
The generated struct for the User
entity will be as follows:
#
ImmutableImmutable fields are fields that can be set only in the creation of the entity. i.e., no setters will be generated for the entity updater.
#
UniquenessFields can be defined as unique using the Unique
method.
Note that unique fields cannot have default values.
#
Storage KeyCustom storage name can be configured using the StorageKey
method.
It's mapped to a column name in SQL dialects and to property name in Gremlin.
#
IndexesIndexes can be defined on multi fields and some types of edges as well. However, you should note, that this is currently an SQL-only feature.
Read more about this in the Indexes section.
#
Struct TagsCustom struct tags can be added to the generated entities using the StructTag
method. Note that if this option was not provided, or provided and did not
contain the json
tag, the default json
tag will be added with the field name.
#
Additional Struct FieldsBy default, ent
generates the entity model with fields that are configured in the schema.Fields
method.
For example, given this schema configuration:
The generated model will be as follows:
In order to add additional fields to the generated struct that are not stored in the database, use external templates. For example:
The generated model will be as follows:
#
Sensitive FieldsString fields can be defined as sensitive using the Sensitive
method. Sensitive fields
won't be printed and they will be omitted when encoding.
Note that sensitive fields cannot have struct tags.
#
AnnotationsAnnotations
is used to attach arbitrary metadata to the field object in code generation.
Template extensions can retrieve this metadata and use it inside their templates.
Note that the metadata object must be serializable to a JSON raw value (e.g. struct, map or slice).
Read more about annotations and their usage in templates in the template doc.
#
Naming ConventionBy convention field names should use snake_case
. The corresponding struct fields generated by ent
will follow the Go convention
of using PascalCase
. In cases where PascalCase
is desired, you can do so with the StorageKey
or StructTag
methods.