FileRef

The FileRef class represents a reference to a file stored in SurrealDB. File references are returned when querying records that contain file fields and provide access to file metadata such as the bucket, key, and media type.

Import:

import { FileRef } from 'surrealdb';

Source: value/file-ref.ts

Properties

bucket

The name of the storage bucket containing the file.

Type: string

Example:

console.log(fileRef.bucket); // "avatars"

key

The unique key identifying the file within its bucket.

Type: string

Example:

console.log(fileRef.key); // "profile-photo.png"

Instance Methods

.toString()

Returns the string representation of the file reference.

Method Syntax
fileRef.toString()

Returns

string - The file reference as a string

.toJSON()

Serializes the file reference for JSON output.

Method Syntax
fileRef.toJSON()

Returns

string - The JSON-safe representation

.equals(other)

Compares this file reference with another for equality.

Method Syntax
fileRef.equals(other)

Parameters

Returns

boolean - True if both file references point to the same file

Example

const ref1 = record1.avatar;
const ref2 = record2.avatar;

if (ref1.equals(ref2)) {
    console.log('Same file');
}

Examples

Reading file references from records

const user = await db.select(new RecordId('users', 'john'));

if (user.avatar instanceof FileRef) {
    console.log('Bucket:', user.avatar.bucket);
    console.log('Key:', user.avatar.key);
}

Querying records with file fields

const [records] = await db.query<[{ avatar: FileRef }[]]>(
    'SELECT avatar FROM users WHERE avatar IS NOT NONE'
);

for (const record of records) {
    console.log(record.avatar.key);
}

See Also

• Value types - Overview of all value types
• File uploads - Working with files in SurrealDB
• Data Types - All custom data types