File

A File is a reference to a file that SurrealDB stores in a bucket: a bucket name and a key. It holds no contents, and has no methods to read or write them. A File maps to the SurrealDB file type in both directions, so a record can hold one in a field. This page documents File and FileMetadata. To read and write the contents of files, use the db.files helpers that Files describes.

from surrealdb import File, FileMetadata

Source: file.py, files.py

Constructor

File(bucket, key)

A bucket or key that is not a str raises TypeError. Because of the leading /, File("images", "a.png") and File("images", "/a.png") are the same file.

from surrealdb import File

avatar = File("images", "photos/avatar.png")
print(avatar.bucket, avatar.key)
print(avatar == File("images", "/photos/avatar.png"))

images /photos/avatar.png
True

Two File values are equal when their buckets and keys are equal, and a File is hashable.

Files in records

A File can be a field value or a query variable, and a file value that the server returns reads back as a File. Storing the reference does not need the bucket or the file to exist. The file type needs SurrealDB 3.0 or later, and a SurrealDB 2.x server refuses a File.

from surrealdb import File, RecordID, Surreal

with Surreal("ws://localhost:8000") as db:
    db.signin({"username": "root", "password": "secret"})
    db.use("surrealdb", "docs")

    db.create(RecordID("person", "tobie"), {
        "avatar": File("images", "photos/avatar.png"),
    })

    person = db.select(RecordID("person", "tobie")).execute()
    print(repr(person["avatar"]))

File(bucket='images', key='/photos/avatar.png')

Text form

str() renders a File as a SurrealQL file literal, for logs and display. The literal syntax accepts only ASCII letters, digits, _, -, . and /, and has no escapes, so a key with a space or an accent has no valid literal. is_literal_safe() tells you whether str() is valid SurrealQL.

print(str(File("images", "photos/avatar.png")))
print(File("images", "my photo.png").is_literal_safe())

f"images:/photos/avatar.png"
False

Do not build query text from str(file). Pass the File as a query variable instead, which works for every key. The db.files helpers do this for you.

FileMetadata

FileMetadata is a frozen dataclass that describes one stored file. db.files.head(file) returns one, or None when the file does not exist, and db.files.list(bucket) returns a list of them.

from surrealdb import File, Surreal

with Surreal("ws://localhost:8000") as db:
    db.signin({"username": "root", "password": "secret"})
    db.use("surrealdb", "docs")

    db.query('DEFINE BUCKET images BACKEND "memory"').execute()

    avatar = File("images", "photos/avatar.png")
    db.files.put(avatar, b"PNG data")

    metadata = db.files.head(avatar)
    print(metadata.file.key, metadata.size)

/photos/avatar.png 8

Buckets are stable from SurrealDB 4.0. On SurrealDB 3.x they are experimental, and the server needs the setting that Files describes.

See also

• •

  Files for the db.files helpers

• •

  Python values for every value class

• •

  Files in SurrealQL