Executing queries

The Java SDK provides methods for executing raw SurrealQL queries against SurrealDB. You can run single or multi-statement queries, bind parameters for safe variable injection, and call server-side functions.

API References

Running a query

The .query() method executes one or more SurrealQL statements and returns a Response. Use .take(int) to extract the result of a specific statement by its zero-based index, or .take(Class, int) to deserialize the result into a typed Java object.

Response response = db.query("SELECT * FROM users; SELECT * FROM posts;");

Value users = response.take(0);
List<Post> posts = response.take(Post.class, 1);

Using query parameters

The .queryBind() method accepts a Map<String, ?> of parameters that are safely injected into the query. Parameterized queries prevent SurrealQL injection and ensure values are properly escaped.

Map<String, Object> params = Map.of("min_age", 18);

Response response = db.queryBind(
    "SELECT * FROM users WHERE age > $min_age",
    params
);

List<User> users = response.take(User.class, 0);

Always prefer .queryBind() over string concatenation when incorporating user-provided values into queries.

Working with query responses

The Response object contains the results of all statements in the query. Use .take(int) to get a raw Value, or .take(Class, int) to deserialize into a POJO. The .size() method returns the number of statement results.

Response response = db.query(
    "CREATE users SET name = 'Alice'; SELECT * FROM users;"
);

int statementCount = response.size();

Value created = response.take(0);
List<User> users = response.take(User.class, 1);

See Value types for details on working with the Value class and type conversions.

Running SurrealDB functions

The .run() method calls a server-side function defined with DEFINE FUNCTION. Pass the function name and any arguments.

Value result = db.run("fn::calculate_total", 100, 0.2);

Learn more

• Surreal API reference for method signatures

• Response API reference for response handling

• Value types for working with query results

• SurrealQL for query language reference

• SurrealQL parameters for parameter syntax in queries

• DEFINE FUNCTION for defining server-side functions