Nuvix

Documents are the records stored in your collections. Each document contains data that follows the collection's attribute structure, plus system fields for tracking and permissions.

This guide uses the Fluent API for Document schemas, which allows you to chain methods for filtering, sorting, and pagination.

Creating documents

Use the .create() method on a collection reference.

import { Client, ID, Permission, Role } from '@nuvix/client';

const nx = new Client()
    .setEndpoint('https://api.nuvix.in/v1')
    .setProject('<PROJECT_ID>');

const document = await nx.database
    .schema('my_app')
    .collection('articles')
    .create(ID.unique(), {
        title: 'Getting Started with Nuvix',
        content: 'This guide covers the basics...',
        published: true,
        views: 0
    }, [
        Permission.read(Role.any()),
        Permission.update(Role.user('author123')),
        Permission.delete(Role.user('author123'))
    ]);

console.log('Created document:', document.$id);

Parameters

Parameter	Type	Required	Description
`documentId`	string	Yes	Unique ID. Use `ID.unique()` for auto-generation.
`data`	object	Yes	Document data matching collection attributes.
`permissions`	string[]	No	Document-level permissions.

System fields

Every document automatically includes these read-only fields:

Field	Type	Description
`$id`	string	Unique document identifier
`$collectionId`	string	Parent collection ID
`$createdAt`	string	ISO 8601 creation timestamp
`$updatedAt`	string	ISO 8601 last update timestamp
`$permissions`	string[]	Document-level permissions

// Retrieve a document by ID
const doc = await nx.database
    .schema('my_app')
    .collection('articles')
    .findById('abc123');

console.log('ID:', doc.$id);
console.log('Created:', doc.$createdAt);

Listing documents

Retrieve documents using the Fluent API. You can chain filters, sorts, and limits before calling .find().

// List all documents (defaults to paginated)
const all = await nx.database
    .schema('my_app')
    .collection('articles')
    .find();

console.log('Total:', all.total);
console.log('Documents:', all.documents);

// With chaining
const filtered = await nx.database
    .schema('my_app')
    .collection('articles')
    .equal('published', true)
    .greaterThan('views', 100)
    .orderDesc('$createdAt')
    .limit(10)
    .offset(0)
    .find();

See the Queries guide for all available chainable methods.

Getting a document

Retrieve a single document by ID using .findById().

const document = await nx.database
    .schema('my_app')
    .collection('articles')
    .findById('abc123');

console.log('Title:', document.title);

Select specific fields

Use .select() to retrieve only the fields you need.

const document = await nx.database
    .schema('my_app')
    .collection('articles')
    .select('title', 'published')
    .findById('abc123');
// Only title and published are returned

Updating documents

Modify an existing document using .update().

const updated = await nx.database
    .schema('my_app')
    .collection('articles')
    .update('abc123', {
        title: 'Updated Title',
        views: 150
    });

console.log('New title:', updated.title);

Update with permissions

Change document permissions by passing the permissions array as the third argument.

await nx.database
    .schema('my_app')
    .collection('articles')
    .update('abc123', {
        published: true
    }, [
        Permission.read(Role.any()),
        Permission.update(Role.team('editors'))
    ]);

Deleting documents

Remove a document using .delete().

await nx.database
    .schema('my_app')
    .collection('articles')
    .delete('abc123');

Deleting a document is permanent and cannot be undone.

Document permissions

Document-level permissions control who can access individual documents.

Permission roles

import { Permission, Role } from '@nuvix/client';

// Roles helpers
Role.any()
Role.users()
Role.user('user123')
Role.team('team123')
Role.team('team123', ['admin'])

Granting permissions on create

await nx.database
    .schema('my_app')
    .collection('private_notes')
    .create(ID.unique(), { 
        content: 'My private note' 
    }, [
        Permission.read(Role.user(userId)),
        Permission.update(Role.user(userId)),
        Permission.delete(Role.user(userId))
    ]);

Bulk operations

Creating multiple documents

Loop through your data to create multiple documents.

const items = [
    { title: 'First', content: '...' },
    { title: 'Second', content: '...' },
    { title: 'Third', content: '...' }
];

const articles = nx.database.schema('my_app').collection('articles');

const created = await Promise.all(
    items.map(item => 
        articles.create(ID.unique(), item)
    )
);

console.log('Created', created.length, 'documents');

Working with arrays

Store and query array fields.

// Query by array contents using .contains()
const tagged = await nx.database
    .schema('my_app')
    .collection('articles')
    .contains('tags', ['javascript'])
    .find();

Working with relationships

Documents can link to other documents through relationship attributes. Use .populate() to include related data.

// Fetch with related data
const post = await nx.database
    .schema('my_app')
    .collection('posts')
    .populate('author') // Include author fields
    .findById('post123');

console.log('Author:', post.author.name);

See the Relationships guide for details.

Queries

Filter and sort documents with chainable methods

Permissions

Control access to your documents

Documents

Queries

Permissions

On this page