# Uuid

Universally unique identifiers for generating unique IDs.

The `Uuid` class provides universally unique identifiers (UUIDs) with support for UUID v4 (random) and UUID v7 (time-ordered) generation.

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

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

## Constructor

### `new Uuid(value)` {#constructor}

Create a UUID from an existing value.

```ts title="Syntax"
new Uuid(uuid) // Clone existing
new Uuid(string) // Parse from string
new Uuid(bytes) // From binary representation
```

#### Parameters
<table>
    <thead>
        <tr>
            <th>Parameter</th>
            <th>Type</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><code>value</code> <label label="required" /></td>
            <td><code>Uuid | string | ArrayBuffer | Uint8Array</code></td>
            <td>Value to create UUID from.</td>
        </tr>
    </tbody>
</table>

#### Examples

```ts
// Parse from string
const uuid = new Uuid('550e8400-e29b-41d4-a716-446655440000');

// From binary
const bytes = new Uint8Array([/* 16 bytes */]);
const uuid = new Uuid(bytes);

// Clone existing
const copy = new Uuid(uuid);
```

## Static methods

### `Uuid.v4()` {#v4}

Generate a random UUID v4.

```ts title="Syntax"
Uuid.v4()
```

#### Returns
`Uuid` - Random UUID v4

#### Example

```ts
const randomId = Uuid.v4();
console.log(randomId.toString());
// '550e8400-e29b-41d4-a716-446655440000'

// Use as record ID
const userId = new RecordId('users', Uuid.v4());
await db.create(userId).content(userData);
```

---

### `Uuid.v7()` {#v7}

Generate a time-ordered UUID v7.

```ts title="Syntax"
Uuid.v7()
```

#### Returns
`Uuid` - Time-ordered UUID v7

> [!NOTE: Tip]
> UUID v7 includes a timestamp component, making it sortable by creation time. This is useful for time-series data and maintaining chronological order.

#### Example

```ts
const timeOrderedId = Uuid.v7();

// Sequential v7 UUIDs are sortable
const id1 = Uuid.v7();
// ... time passes ...
const id2 = Uuid.v7();

// id1 < id2 (lexicographically)
```

## Instance methods

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

Convert to string representation.

```ts title="Syntax"
uuid.toString()
```

#### Returns
`string` - UUID string in standard format (`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`)

#### Example

```ts
const uuid = Uuid.v4();
console.log(uuid.toString());
// '550e8400-e29b-41d4-a716-446655440000'
```

---

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

Serialise for JSON.

```ts title="Syntax"
uuid.toJSON()
```

#### Returns
`string` - UUID string

---

### `.toUint8Array()` {#touint8array}

Get the binary representation as Uint8Array.

```ts title="Syntax"
uuid.toUint8Array()
```

#### Returns
`Uint8Array` - 16-byte binary representation

#### Example

```ts
const uuid = Uuid.v4();
const bytes = uuid.toUint8Array();
console.log(bytes.length); // 16
```

---

### `.toBuffer()` {#tobuffer}

Get the binary representation as ArrayBuffer.

```ts title="Syntax"
uuid.toBuffer()
```

#### Returns
`ArrayBufferLike` - Binary representation

---

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

Check if two UUIDs are equal.

```ts title="Syntax"
uuid.equals(other)
```

#### Returns
`boolean` - True if equal

## Complete examples

### Session management

```ts
import { Surreal, Uuid, RecordId, DateTime, Duration, Table } from 'surrealdb';

const db = new Surreal();
await db.connect('ws://localhost:8000');

// Create session with UUID
const sessionId = Uuid.v4();
const session = await db.create(new RecordId('sessions', sessionId))
    .content({
        user: userId,
        created_at: DateTime.now(),
        expires_at: DateTime.now().plus(new Duration('24h')),
        ip_address: '192.168.1.1'
    });

console.log('Session ID:', sessionId.toString());
```

### Time-ordered records

```ts
// Use v7 for time-series data
const events = [];

for (let i = 0; i < 100; i++) {
    const eventId = Uuid.v7();
    
    await db.create(new RecordId('events', eventId)).content({
        type: 'user_action',
        timestamp: DateTime.now(),
        data: { action: 'click', target: 'button' }
    });
    
    events.push(eventId);
}

// Events are naturally sorted by creation time
```

### Unique identifiers

```ts
// Generate unique IDs for various purposes
const requestId = Uuid.v4();
const correlationId = Uuid.v4();
const traceId = Uuid.v7(); // Time-ordered for distributed tracing

await db.create(new Table('requests')).content({
    id: requestId,
    correlation_id: correlationId,
    trace_id: traceId,
    timestamp: DateTime.now()
});
```

### API keys

```ts
// Generate API keys
function generateApiKey(): string {
    return `api_${Uuid.v4().toString().replace(/-/g, '')}`;
}

const apiKey = generateApiKey();
console.log(apiKey); // 'api_550e8400e29b41d4a716446655440000'

await db.create(new Table('api_keys')).content({
    key: apiKey,
    user: userId,
    created_at: DateTime.now()
});
```

### Distributed system IDs

```ts
// Use UUID v7 for distributed systems (sortable)
class IdGenerator {
    static generateOrderId(): Uuid {
        return Uuid.v7(); // Time-ordered
    }
    
    static generateTransactionId(): Uuid {
        return Uuid.v7(); // Time-ordered
    }
    
    static generateRandomId(): Uuid {
        return Uuid.v4(); // Random
    }
}

const orderId = IdGenerator.generateOrderId();
const txnId = IdGenerator.generateTransactionId();
```

### File upload tracking

```ts
// Track file uploads with UUIDs
async function uploadFile(file: File): Promise<string> {
    const uploadId = Uuid.v4();
    
    await db.create(new RecordId('uploads', uploadId)).content({
        filename: file.name,
        size: file.size,
        mime_type: file.type,
        uploaded_at: DateTime.now(),
        status: 'processing'
    });
    
    return uploadId.toString();
}
```

### Parsing and validation

```ts
// Parse UUID from user input
function validateUuid(input: string): Uuid | null {
    try {
        return new Uuid(input);
    } catch (error) {
        console.error('Invalid UUID format');
        return null;
    }
}

const userInput = '550e8400-e29b-41d4-a716-446655440000';
const uuid = validateUuid(userInput);

if (uuid) {
    const record = await db.select(new RecordId('items', uuid));
}
```

### Batch ID generation

```ts
// Generate multiple UUIDs
function generateBatchIds(count: number, useV7 = false): Uuid[] {
    const ids: Uuid[] = [];
    
    for (let i = 0; i < count; i++) {
        ids.push(useV7 ? Uuid.v7() : Uuid.v4());
    }
    
    return ids;
}

const randomIds = generateBatchIds(100); // 100 random UUIDs
const sortableIds = generateBatchIds(100, true); // 100 time-ordered UUIDs
```

## UUID v4 vs UUID v7

### UUID v4 (random)

- **Pros:** Truly random, no predictability
- **Cons:** Not sortable, no time information
- **Use when:** You need unpredictable, secure IDs

```ts
const randomId = Uuid.v4();
```

### UUID v7 (time-ordered)

- **Pros:** Sortable, includes timestamp, better for database indexes
- **Cons:** Slightly predictable (timestamp component)
- **Use when:** You need sortable IDs or time-series data

```ts
const timeOrderedId = Uuid.v7();
```

## Best practices

### 1. Choose the right version

```ts
// Good: v7 for time-series and events
const eventId = Uuid.v7();

// Good: v4 for security tokens
const token = Uuid.v4();
```

### 2. Use with RecordId

```ts
// Good: UUID as record ID
const userId = new RecordId('users', Uuid.v7());

// Good: Provides uniqueness and sortability
await db.create(userId).content(userData);
```

### 3. Validate user input

```ts
// Good: Validate before use
try {
    const uuid = new Uuid(userInput);
    await processUuid(uuid);
} catch (error) {
    return { error: 'Invalid UUID format' };
}
```

### 4. Store as UUID type

```ts
// Good: Store as UUID
await db.create(table).content({
    session_id: Uuid.v4()
});

// Avoid: Store as string
await db.create(table).content({
    session_id: Uuid.v4().toString()
});
```

## See also

- [RecordId](/docs/reference/javascript/api/values/record-id.md) - Record identifiers
- [Data types overview](/docs/reference/javascript/api/values/) - All custom data types
- [Query builders](/docs/reference/javascript/api/queries/) - Using Uuid in queries
- [SurrealQL UUID](/docs/reference/query-language/language-primitives/data-types/uuids.md) - Database UUID type