# Sample queries

Learn how to get started with SurrealDB

Welcome to SurrealDB! In this guide, you will learn about the various ways you can start using SurrealDB with interactive examples. Before we dive in, let's cover some basics.

## Running queries in SurrealDB

Much like any other database, you can communicate with SurrealDB by executing queries.

Queries are written using [SurrealQL](/docs/reference/query-language.md), SurrealDB's powerful and flexible query language. While SurrealQL takes inspiration from traditional SQL, it is designed to be more expressive and flexible, allowing you to query your data in a variety of ways.

Let's take a look at some of the basic queries you can run in SurrealDB.

### Creating data with CREATE

Before we can start querying data, we need to create some records. This can be done using the [CREATE statement](/docs/reference/query-language/statements/create.md), which is used to add new records to the database.

The following example demonstrates how to create a record in the `category` table, initialised with a `name` field and a `created_at` field. Press the *"Run query"* button to execute the query and view the response.

<br />

```surql
CREATE category SET
	name = 'Technology',
	created_at = time::now();
```

After executing this statement, the `category` record is created in the database, and a randomly generated unique id known as a [Record ID](/docs/reference/query-language/language-primitives/data-types/record-ids.md) is assigned to it. This ID represents the primary key of our record, and can be used to reference the record in future queries.

When creating records, you can also explicitly set the record ID. This can be useful when you are able to use predictable unique record IDs such as `company:surrealdb` or `planet:earth`. In the following example, we create a person record with the ID `john`, and set the `first`, `last`, `age`, `admin`, and `signup_at` fields.

<br />

```surql
CREATE person:john SET
	first = 'John',
	last = 'Adams',
	age = 29,
	admin = true,
	signup_at = time::now();
```

One of the many powerful features of SurrealDB is the ability to write subqueries, which in the following example is used to populate the `category` field of the `article` record with the ID of the `Technology` category.

<br />

```surql
CREATE article SET
	created_at = time::now(),
	author = person:john,
	title = 'Lorem ipsum dolor',
	text = 'Donec eleifend, nunc vitae commodo accumsan, mauris est fringilla.',
	category = SELECT VALUE id FROM ONLY category WHERE name = 'Technology' LIMIT 1;
```

### Querying data with SELECT

After inserting records into your database, you can now use the [SELECT statement](/docs/reference/query-language/statements/select.md) to retrieve data. While this statement will be familiar to anyone who has used traditional SQL before, SurrealDB's SELECT statement includes additional powerful features inspired by NoSQL databases.

For example, in addition to selecting records from a single table, you can also select records from multiple tables, or select specific records by their Record ID.

<br />

```surql
-- Select all records from a table
SELECT * FROM article;

-- Select records from multiple tables
SELECT * FROM category, person;

-- Selecting specific records
SELECT * FROM person:john;
```

The [SELECT statement](/docs/reference/query-language/statements/select.md) offers a variety of different features, such as the ability to filter on fields, fetch and resolve record id contents, and the ability to access data directly from Record IDs without the need of JOINs or complex queries.

The following query combines a number of such features:
- **Filtering**: Use the `WHERE` clause to only include records where the author's age is less than 30.
- **Fetching**: Use the `.*` idiom to replace record ids with their actual field values.
- **Specific fields**: Only want to retrieve the title and author fields from the article table.
- **Record links**: Structure the field data from the author in a preferred format, including an alias for the field `name.full`.

```surql
SELECT
	title,
	category.*,
	author.{
		age,
		name: name.full,
	}
FROM article
WHERE author.age < 30;
```

### Modifying data with UPDATE

Records can be updated using the [UPDATE](/docs/reference/query-language/statements/update.md) statement, which allows you to modify the contents of existing records.

Much like the `SELECT` statement, you can pass both table names and individual record IDs to the `UPDATE` statement. This allows you to update specific records, or update multiple records at once.

```surql
UPDATE person:john SET
	age += 1,
	admin = false;
```

The `UPDATE` statement offers a variety of features to further filter down records, and apply different update strategies. The following example demonstrates how we can merge new data into records matching a specific condition.

<br />

```surql
UPDATE person MERGE {
	age: 30,
	admin: false
}
```

In addition to the `UPDATE` statement, SurrealDB also offers an [UPSERT statement](/docs/reference/query-language/statements/upsert.md), which has the added functionality of creating a record if it does not already exist. This can be useful when you want to update a record if it exists, or create it if it does not.

### Deleting data with DELETE

You can also delete records from your database using the [DELETE statement](/docs/reference/query-language/statements/delete.md). This statement allows you to remove records from your database, either by specifying the record ID, or by using specific conditions.

The following example demonstrates the use of the `RETURN` clause, which instructs SurrealDB to return the records before they are deleted.

<br />

```surql
DELETE article WHERE author.name.first = 'David' RETURN BEFORE;
```

Congratulations, you're now on your way to database and API simplicity! For the next steps, we will explore the different ways to integrate SurrealDB into your applications.