(types)=
# Supported Go types and their format
## Supported Go types 

SQLair supports the following types:
- In input expressions:
  - structs
  - maps
  - slices
- In output expressions:
  - structs
  - maps

All types used with SQLair must be named so they can be referenced in the query.

## Type format
### Structs

For a struct to be usable by SQLair, all struct fields that correspond to a
database column must be tagged with a `db` tag containing the column name. These
fields must be public (i.e. start with a capital letter), though the struct
itself does not have to be. Any fields without a tag will be ignored.

If a struct contains an embedded struct then SQLair will treat the fields of the
embedded structs as if they were fields in the parent struct.

For example:
```go
type Person struct {
    Name    string  `db:"name"`
    ID      int     `db:"id_number"`
    DoB     string  `db:"date_of_birth"`
    Weight  int
    height  int
}
```
In this example the `Weight` and `height` fields will be ignored by SQLair.

#### The "omitempty" keyword

In a struct tag, the `omitempty` keyword tells SQLair to omit the column
from an insert operation if the value in the
corresponding struct field zeroed.

This is useful if the content of the column is generated by the database, e.g.
if it has an auto-increment directive.

To add the `omitempty` keyword, write it in the `db` tag after the column name.

For example:
```go
type Address struct {
    ID   string `db:"id, omitempty"`
    City string `db:"city"`
}
```

```{admonition} See more
:class: tip
{ref}`insert-statements`
```
### Maps

Named maps can be used with SQLair and must have a key with a base type of
`string`. This is because SQLair uses the column names as keys when reading from
and writing to the map. The value type of the map can be anything.

For example:
```go
type Cols map[string]int
```

#### sqlair.M
For convenience, SQLair provides a named map type
[`sqlair.M`](https://pkg.go.dev/github.com/canonical/sqlair#M) which has the
type `map[string]any`.

### Slices

Named slices can only be used as inputs and will expand into a comma separated
list of input placeholders for each value in the slice. The slice must be named
and can be of any type.

For example:
```go
type Names []string
```

#### sqlair.S
For convenience, SQLair provides a named slice type
[`sqlair.S`](https://pkg.go.dev/github.com/canonical/sqlair#S) which has the
type `[]any`.