Schema modes

SurrealDB supports both schemaless workflows (insert records of varying shape into the same table) and schemafull definitions when you want validation and clearer contracts. This page focuses on the schemaless style that feels closest to typical document databases.

Schema flexibility

Document model databases are often chosen because:

1. Data organisation: Data is contained in self-describing documents, typically in JSON or a similar format. Relationships can be done within the document itself (embedding) or via record links to other documents.

2. Schema flexibility: Schemas are often flexible, allowing for documents of varying shapes in the same collection (or table-like structure). When you need stricter rules, you can use DEFINE TABLE and DEFINE FIELD.

Creating and managing documents

In SurrealDB, you can create a database and then store collections of documents (often referred to as “tables”) without strict schema definitions. This is conceptually similar to creating a table in a relational database, but you do not need to define all columns upfront. Instead, you can insert JSON-like objects directly.

Adding a document

CREATE users CONTENT {
    name: "Alice Smith",
    email: "alice@example.com",
    age: 29,
    addresses: [
        {
            type: "home",
            address_line: "123 Maple St",
            city: "Springfield",
            country: "USA"
        },
        {
            type: "work",
            address_line: "456 Oak Ave",
            city: "Metropolis",
            country: "USA"
        }
    ]
};

Here, a user document includes nested objects (addresses) in the same record. You can add nested objects or properties without modifying a central schema first.

Retrieving documents

SELECT * FROM users;

The query returns all documents in the users table, similar to a traditional SQL SELECT:

[
	{
		addresses: [
			{
				address_line: '123 Maple St',
				city: 'Springfield',
				country: 'USA',
				type: 'home'
			},
			{
				address_line: '456 Oak Ave',
				city: 'Metropolis',
				country: 'USA',
				type: 'work'
			}
		],
		age: 29,
		email: 'alice@example.com',
		id: 'users:xyz123',
		name: 'Alice Smith'
	}
]

SurrealDB automatically generates a unique id for the document. You can also specify your own custom IDs if you prefer more human-readable or domain-specific identifiers.

Next steps

For concept mapping to other document stores and MongoDB-style SurrealQL examples, see Common patterns.