# FileRef

The FileRef class represents a reference to a file stored in SurrealDB.

The `FileRef` class represents a reference to a file stored in SurrealDB. File references are returned when querying records that contain [file fields](/docs/reference/query-language/language-primitives/data-types/files.md) and provide access to file metadata such as the bucket, key, and media type.

**Import:**
```ts
import { FileRef } from 'surrealdb';
```

**Source:** [value/file-ref.ts](https://github.com/surrealdb/surrealdb.js/blob/main/packages/sdk/src/value/file-ref.ts)

## Constructor

```ts
new FileRef(bucket: string, key: string)
```

### Parameters
<table>
    <thead>
        <tr>
            <th>Parameter</th>
            <th>Type</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><code>bucket</code> <label label="required" /></td>
            <td><code>string</code></td>
            <td>The name of the storage bucket.</td>
        </tr>
        <tr>
            <td><code>key</code> <label label="required" /></td>
            <td><code>string</code></td>
            <td>The unique key identifying the file within the bucket.</td>
        </tr>
    </tbody>
</table>

### Example

```ts
const fileRef = new FileRef('avatars', 'profile-photo.png');

await db.create(new RecordId('users', 'john')).content({
    name: 'John',
    avatar: fileRef
});
```

## Properties

### `bucket` {#bucket}

The name of the storage bucket containing the file.

**Type:** `string`

**Example:**
```ts
console.log(fileRef.bucket); // "avatars"
```

### `key` {#key}

The unique key identifying the file within its bucket.

**Type:** `string`

**Example:**
```ts
console.log(fileRef.key); // "profile-photo.png"
```

## Instance methods

### `.toString()` {#tostring}

Returns the string representation of the file reference.

```ts title="Method Syntax"
fileRef.toString()
```

#### Returns
`string` - The file reference as a string

---

### `.toJSON()` {#tojson}

Serializes the file reference for JSON output.

```ts title="Method Syntax"
fileRef.toJSON()
```

#### Returns
`string` - The JSON-safe representation

---

### `.equals(other)` {#equals}

Compares this file reference with another for equality.

```ts title="Method Syntax"
fileRef.equals(other)
```

#### Parameters
<table>
    <thead>
        <tr>
            <th>Parameter</th>
            <th>Type</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><code>other</code> <label label="required" /></td>
            <td><code>unknown</code></td>
            <td>The value to compare against.</td>
        </tr>
    </tbody>
</table>

#### Returns
`boolean` - True if both file references point to the same file

#### Example
```ts
const ref1 = record1.avatar;
const ref2 = record2.avatar;

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

## Examples

### Reading file references from records

```ts
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

```ts
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](/docs/reference/javascript/concepts/value-types.md) - Overview of all value types
- [File uploads](/docs/reference/query-language/language-primitives/data-types/files.md) - Working with files in SurrealDB
- [Data types](/docs/reference/javascript/api/values/) - All custom data types