Querying Data in SurrealDB

In this section, you will explore some of the ways you can query data in SurrealDB using SurrealQL, GraphQL or via any of the available SDKs. Regardless of the method you choose, SurrealDB provides powerful querying capabilities that allow you to retrieve, filter, and manipulate data efficiently and effectively.

Now, let’s explore the different methods to query data in SurrealDB.

SurrealQL

SurrealQL is our powerful database query language that closely resembles traditional SQL but comes with unique differences and improvements.

Designed to provide developers with a seamless and intuitive way to interact with SurrealDB, SurrealQL offers a familiar syntax and supports various statement types, allowing you to perform complex database operations efficiently.

To get started with SurrealQL, explore the SurrealQL documentation to learn about the statements available. These statements enable you to perform a wide range of database operations, from querying data to modifying records and managing database structures.

Additionally, SurrealQL provides a rich set of database functions that enhance its capabilities. These functions allow you to perform advanced operations and leverage the full potential of SurrealDB’s features. Whether you are working with data retrieval, manipulation, or complex computations, SurrealQL’s functions offer the tools you need to build robust and scalable applications.

Getting Started

The easiest way to get started with SurrealQL is to use Surrealist. This interactive environment allows you to experiment with SurrealQL statements and see the results in a tabular format. You can either set up a sandbox instance, a remote or local instance.

You can use Surrealist to learn about the syntax and features of SurrealQL and to develop your queries and scripts.

To familiarize yourself with SurrealQL, explore the various statement and their syntax. The statements pages provides comprehensive examples and explanations for each statement type, helping you understand how to construct queries and interact with SurrealDB effectively.

SurrealQL empowers you to leverage the full potential of SurrealDB and enables you to build robust and scalable applications. Let’s dive into the world of SurrealQL and unlock the capabilities of SurrealDB together!

Querying Options

When using SurrealQL, there are several options available to interact with your database instance depending on your environment and needs.

• Surrealist (Recommended): Surrealist is an interactive environment that allows you to experiment with SurrealQL statements and see the results in a tabular format. It is a great tool for learning about the syntax and features of SurrealQL and for developing your queries and scripts.

• CLI: The SurrealDB Command Line Interface (CLI) provides a powerful way to interact with the database directly from your terminal. You can execute SurrealQL queries, manage database structures, and perform administrative tasks using the CLI.

• WebSocket: SurrealDB supports WebSocket connections, allowing you to execute SurrealQL queries in real-time. This option is ideal for applications that require low-latency communication and real-time updates.

• HTTP: You can send HTTP requests to the /sql endpoint to execute SurrealQL queries. This method is useful for integrating SurrealDB with web applications and services that communicate over HTTP.

  • Postman: Using Postman or any other HTTP client, you can send a POST request to the /sql endpoint with your SurrealQL query in the body. This method provides flexibility and can be useful for testing and automation purposes.

• RPC: SurrealDB also supports RPC, allowing you to interact with the database programmatically over a network.

Using RPC

SurrealDB also supports RPC, allowing you to interact with the database programmatically over a network.

1. Set up an RPC client: Depending on your programming language, you can use various libraries to create an RPC client. Here is an example using JavaScript with the node-fetch library:

   const fetch = require('node-fetch');
   
   async function querySurrealDB() {
     // Create a new person record
     await fetch('http://localhost:8000/rpc', {
       method: 'POST',
       headers: {
         'Content-Type': 'application/json',
       },
       body: JSON.stringify({
         method: 'query',
         params: ['CREATE person SET name = "John Doe"; SELECT * FROM person;'],
       }),
     });
   
     const data = await response.json();
   }
   
   querySurrealDB();
   

2. Execute the RPC call: Run your script to send the RPC request and receive the response from SurrealDB.

GraphQL

Available since: v2.0.0

SurrealDB also supports GraphQL, allowing you to interact with the database using the familiar syntax. Currently, you can use the GraphQL integration via Surrealist, our intuitive user interface specifically designed for SurrealDB, or over HTTP via a GraphQL Client such as GraphiQL or Postman at the localhost:8000/graphql endpoint.

With Surrealist, you can easily connect to any SurrealDB instance, execute queries in real time, explore your tables, and design your schemas - all in one place.

The GraphQL view allows you to define and retrieve only the data you need, giving you more control and efficiency in how you interact with your database.

Getting Started

To get started with GraphQL, you can use the GraphQL integration in Surrealist. Once you have connected to your SurrealDB instance, you can explore your tables, execute queries, and manage your data in a user-friendly interface.

Querying Options

When using GraphQL, there are several options available to interact with your database instance depending on your environment and needs.

• Surrealist: Surrealist is an interactive environment that allows you to experiment with SurrealQL statements and see the results in a tabular format. It is a great tool for learning about the syntax and features of SurrealQL and for developing your queries and scripts.

• HTTP: You can send HTTP requests to the /graphql endpoint to execute GraphQL queries. This method is useful for integrating SurrealDB with web applications and services that communicate over HTTP.

SDKs

Another way to interact with SurrealDB is to use one of the available SDKs. The SDKs provide a convenient way to query data, insert records, and manage database operations programmatically.

SurrealDB offers a variety of SDKs that allow you to interact with the database programmatically. These SDKs provide a convenient and efficient way to query data, insert records, and manage database operations using your preferred programming language.

Available SDKs

SurrealDB supports SDKs for several popular programming languages, including:

• JavaScript/TypeScript: The JavaScript/TypeScript SDK allows you to interact with SurrealDB from web applications, Node.js environments, and other JavaScript-based platforms. It provides a comprehensive set of methods to perform queries, manage records, and handle database transactions.

• Python: The Python SDK offers a seamless way to integrate SurrealDB with your Python applications. Whether you are building web applications, data analysis tools, or automation scripts, the Python SDK provides the necessary functions to interact with the database efficiently.

• .NET: The .NET SDK allows you to interact with SurrealDB using the .NET framework. It provides a comprehensive set of methods to perform queries, manage records, and handle database transactions, making it suitable for building robust and scalable applications.

• Rust: The Rust SDK leverages the safety and performance features of the Rust programming language. It allows you to interact with SurrealDB in a type-safe manner, ensuring that your database operations are both efficient and reliable.

Getting Started with SDKs

To get started with any of the SDKs, you need to install the appropriate package for your programming language. Once installed, you can initialize the SDK and connect to your SurrealDB instance. Here is an example of how to get started with the JavaScript SDK:

import { Surreal } from 'surrealdb';

const db = new Surreal('http://localhost:8000');

await db.connect('root', 'root');

type Person = {
	id: string;
	name: string;
};

// Assign the variable on the connection
const result = await db.query<[Person[], Person[]]>(
	'CREATE person SET name = "John"; SELECT * FROM type::table($tb);',
	{ tb: 'person' }
);

// Get all of the results from the second query
const people = result[1].result;

Learn More

To learn more about the available options for querying data in SurrealDB, explore the following resources:

• SurrealQL documentation
• Surrealist documentation