> Full SurrealDB documentation index: https://surrealdb.com/docs/llms.txt

# File

models.File in the Go SDK for the SurrealDB file kind: a pointer to a file in a bucket, written f"bucket:/key" in SurrealQL, NewFile, the Bucket and Key fields, sending a file as a query variable, and its String form.

A `models.File` points to a file in a SurrealDB bucket, as the SurrealQL value `f"bucket:/key"` does. It holds the name of the bucket and the key of the file, not the content of the file. This page documents the type and how to send one. Files are an experimental feature of SurrealDB. A server turns the feature on with `--allow-experimental files`, but the SDK always decodes `File` values.

**Package:** `github.com/surrealdb/surrealdb.go/v2/pkg/models`

**Source:** [pkg/models/file.go](https://github.com/surrealdb/surrealdb.go/blob/main/pkg/models/file.go)

---

## Definition {#definition}

```go
type File struct {
	Bucket string
	Key    string
}
```

| Field | Description |
| --- | --- |
| `Bucket` | The name of the bucket the file is in |
| `Key` | The path of the file in the bucket, starting with a slash |

---

## Constructor {#constructor}

### `NewFile` {#newfile}

Returns a `File` for the file at `key` in `bucket`. It adds a leading slash to `key` when `key` has none.

```go title="Syntax"
f := models.NewFile(bucket, key)
```

**Returns:** `File`

```go
f := models.NewFile("docs", "report.pdf")
fmt.Println(f.Bucket, f.Key)
```

```text title="Output"
docs /report.pdf
```

---

## Files in queries {#queries}

Send a `File` as a query variable. The SDK sends it as its own kind, so any bucket and key work:

```go
results, err := surrealdb.Query[[]byte](ctx, db, "RETURN $file.get()", map[string]any{
	"file": models.NewFile("docs", "report.pdf"),
})
```

A file that the server returns, such as one stored in a field of a record, decodes into a `File`, including from `any`. See [Files](/docs/reference/query-language/language-primitives/data-types/files.md) for the functions that read and write the content of a file.

---

## Text form {#string}

`.String()` returns the file as a file string, such as `f"docs:/report.pdf"`. It puts a backslash before each character that is not an ASCII letter or digit, `_`, `-`, `.`, or a `/` in the key. For example, `models.NewFile("docs", "my report.pdf")` gives `f"docs:/my\ report.pdf"`. A file string has no escape syntax, so SurrealDB reads the result back as the same file only when no character needed a backslash. Send a `File` as a variable rather than writing its text into a query.

---

## See also

- [Value types](/docs/reference/golang/concepts/value-types.md#files) for how values convert
- [Files](/docs/reference/query-language/language-primitives/data-types/files.md) for the SurrealQL kind