Class Surreal

java.lang.Object
com.surrealdb.Native
com.surrealdb.Surreal
All Implemented Interfaces:
AutoCloseable
public class Surreal extends Native implements AutoCloseable
The Surreal class provides methods to interact with a Surreal database. It includes functionality to connect to the database, sign in with different scopes, set the namespace and database, execute queries, and perform CRUD operations on records.

Methods that take a String target or table treat it as a table name and nothing else: the name is sent to the server as a bound table value, so it is never parsed as SurrealQL. An empty table name, an empty list of tables, and a table name containing ':', such as "person:tobie", are rejected with a SurrealException. A name with ':' is almost always a record id passed by mistake: use RecordId to address a single record. Record contents are always sent as bound parameters. The table inside a RecordId or RecordIdRange is part of that value and is sent bound as well.

  • Constructor Details

    • Surreal

      public Surreal()
      Constructs a new Surreal object.

  • Method Details

    • connect

      public Surreal connect(String connect)
      Establishes a connection to the Surreal database using the provided connection string.
      Parameters:
      connect - the connection string used to establish the connection
      Returns:
      the current instance of the Surreal class

    • version

      public String version()
      Returns the server version (semantic version string, e.g. "1.0.0").
      Returns:
      the server version string
      Throws:
      SurrealException - if the request fails

    • health

      public boolean health()
      Performs a health check against the server.
      Returns:
      true if the server is healthy
      Throws:
      SurrealException - if the health check fails

    • run

      public Value run(String name, Object... args)
      Runs a SurrealDB function by name with the given arguments (e.g. array::add, math::mean). Implemented via a SurrealQL RETURN query.
      Parameters:
      name - the function name (e.g. "array::add" or "array::add<1.0.0>" for a version). Only identifier segments joined by :: are accepted; anything else is rejected rather than sent.
      args - the arguments to pass to the function (converted to Surreal values)
      Returns:
      the result Value
      Throws:
      SurrealException - if the run fails

    • exportSql

      public boolean exportSql(String path)
      Exports the database to a file. Supported by HTTP and local engines; not by WebSocket.
      Parameters:
      path - file path to write the export
      Returns:
      true on success
      Throws:
      SurrealException - if export fails or backups are not supported

    • importSql

      public boolean importSql(String path)
      Imports the database from a file. Supported by HTTP and local engines; not by WebSocket.
      Parameters:
      path - file path to read the import from
      Returns:
      true on success
      Throws:
      SurrealException - if import fails or backups are not supported

    • selectLive

      public LiveStream selectLive(String table)
      Starts a live query on the given table and returns a blocking stream of notifications (CREATE, UPDATE, DELETE).

      This method blocks until the live query subscription is fully established on the server. If the subscription fails (e.g. the table does not exist), a SurrealException is thrown immediately rather than being deferred to the first LiveStream.next() call.

      Call LiveStream.next() in a loop to receive notifications and LiveStream.close() when done. The returned stream implements AutoCloseable for use in try-with-resources.

      Parameters:
      table - table name to watch (must already exist)
      Returns:
      a LiveStream; the caller must call LiveStream.close() when done
      Throws:
      SurrealException - if live queries are not supported, the table does not exist, or the subscription fails

    • selectLive

      public LiveStream selectLive(String table, boolean diff)
      Starts a live query on the given table, optionally in diff mode.

      In diff mode (LIVE SELECT DIFF) each notification's value is an array of JSON Patch operations (op, path, value) describing how the record changed, rather than the record itself. Otherwise this behaves like selectLive(String).

      Parameters:
      table - table name to watch (must already exist)
      diff - whether notifications carry JSON Patch operations instead of records
      Returns:
      a LiveStream; the caller must call LiveStream.close() when done

      Diff mode needs SurrealDB 3.3.0 or later, for the server and for the embedded engine. Earlier versions can leak fields hidden by field-level SELECT permissions through diff patches (advisory GHSA-pm6c-q8rh-92m8), so it is refused there.

      Throws:
      SurrealException - if live queries are not supported, the table does not exist, the subscription fails, or diff mode is requested on SurrealDB before 3.3.0

    • kill

      public void kill(String queryId)
      Stops the live query with the given id. After the server processes the kill, the query delivers no further notifications.

      The id is the UUID returned by LiveStream.getQueryId() (or carried by each LiveNotification). A kill does not by itself close a local LiveStream: a thread blocked in LiveStream.next() keeps waiting (no further notifications arrive, on both the embedded and WebSocket engines). Call LiveStream.close() to release a local stream and unblock next(). Use kill for a live query you only hold the id of (e.g. one started elsewhere or read from a notification).

      A kill the server rejects raises a QueryException ("Cannot execute KILL statement using id: ..."), as for an id that names no live query, one that was already killed, or one this session may not kill.

      Parameters:
      queryId - the live query UUID to terminate
      Throws:
      SurrealException - if the id is not a valid UUID, the request cannot be sent, or the server rejects the kill

    • kill

      public void kill(UUID queryId)
      Stops the live query with the given id.
      Parameters:
      queryId - the live query UUID to terminate
      See Also:

    • signin

      public Token signin(Credential credential)
      Signs in with the given credential. Supports RootCredential, NamespaceCredential, DatabaseCredential, RecordCredential, and BearerCredential.

      For more details, check the authentication documentation.

      Parameters:
      credential - the credentials (RootCredential, NamespaceCredential, DatabaseCredential, RecordCredential, or BearerCredential)
      Returns:
      a Token representing the session after a successful sign-in
      Throws:
      SurrealException - if the credential type is unsupported or RecordCredential ns/db cannot be resolved

    • signup

      public Token signup(RecordCredential record)
      Signs up a record user with the given record access credentials. When namespace or database are null on the record, the current session values from useNs/useDb are used.
      Parameters:
      record - record signup credentials (namespace, database, access, params; ns/db may be null to use session)
      Returns:
      tokens (access and optional refresh) returned by the server
      Throws:
      SurrealException - if namespace or database cannot be resolved (call useNs/useDb first when omitting)

    • authenticate

      public Surreal authenticate(String token)
      Authenticates the current connection with a JWT token (e.g. the access token from signin).
      Parameters:
      token - the access token string
      Returns:
      the current instance

    • invalidate

      public Surreal invalidate()
      Invalidates the authentication for the current connection.
      Returns:
      the current instance

    • refresh

      public Token refresh(Token token)
      Exchanges a refresh token for a new access/refresh pair and authenticates this session with the new access token. The refresh token passed in is consumed: use the one in the returned Token next time.

      Refresh tokens are issued by record access methods defined WITH REFRESH.

      Parameters:
      token - a token pair from signin(Credential), signup(long, String, String, String, long) or a previous refresh
      Returns:
      the new token pair
      Throws:
      IllegalArgumentException - if the token has no refresh part

    • revoke

      public Surreal revoke(Token token)
      Revokes the refresh token of a token pair, so it can no longer be exchanged with refresh(Token). This does not sign the session out; use invalidate() for that.
      Parameters:
      token - the token pair whose refresh token to revoke
      Returns:
      the current instance
      Throws:
      IllegalArgumentException - if the token has no refresh part

    • set

      public Surreal set(String name, Object value)
      Defines a variable on this session. It is available as $name in every later query on this session, until unset(String).
      Parameters:
      name - the variable name, without the $
      value - the value; converted like a query binding
      Returns:
      the current instance

    • unset

      public Surreal unset(String name)
      Removes a variable defined with set(String, java.lang.Object).
      Parameters:
      name - the variable name, without the $
      Returns:
      the current instance

    • info

      public Optional<Value> info()
      Returns the record of the signed-in record user ($auth).
      Returns:
      the user's record, or empty when the session is not signed in as a record user

    • info

      public <T> Optional<T> info(Class<T> type)
      Returns the record of the signed-in record user, converted to type.
      Parameters:
      type - the class to convert the record to
      Returns:
      the user's record, or empty when the session is not signed in as a record user

    • newSession

      public Surreal newSession()
      Creates a new session that shares the same connection. The new session starts as a copy of this one (namespace, database, variables and authentication) and changes to either session after that do not affect the other. Use this for multi-session support.
      Returns:
      a new Surreal instance representing a separate session

    • beginTransaction

      public Transaction beginTransaction()
      Starts a client-side transaction. Use Transaction.query(String) for operations and Transaction.commit() or Transaction.cancel() to complete it.
      Returns:
      a new Transaction instance

    • useNs

      public Surreal useNs(String ns)
      Sets the namespace for the Surreal instance. The current namespace and database from the server are stored; use getNamespace() and getDatabase() to read them.
      Parameters:
      ns - the namespace to use
      Returns:
      this instance for chaining

    • useDb

      public Surreal useDb(String db)
      Sets the database for the current instance. The current namespace and database from the server are stored; use getNamespace() and getDatabase() to read them.
      Parameters:
      db - the database name to use
      Returns:
      this instance for chaining

    • useDefaults

      public Surreal useDefaults()
      Sets the default namespace and database. The actual defaults from the server are stored; use getNamespace() and getDatabase() to read them.
      Returns:
      this instance for chaining

    • getNamespace

      public String getNamespace()
      Returns the current namespace set by the last useNs(String), useDb(String), or useDefaults() call (from the server response), or inherited from the parent by newSession(). Null if none of those have happened since connect(String). A USE statement run through query(String) is not reflected here.
      Returns:
      the current namespace, or null

    • getDatabase

      public String getDatabase()
      Returns the current database set by the last useNs(String), useDb(String), or useDefaults() call (from the server response), or inherited from the parent by newSession(). Null if none of those have happened since connect(String). A USE statement run through query(String) is not reflected here.
      Returns:
      the current database, or null

    • query

      public Response query(String sql)
      Executes a SurrealQL query on the database.

      For more details, check the SurrealQL documentation.

      Parameters:
      sql - the SurrealQL query to be executed
      Returns:
      a Response object containing the results of the query

    • query

      public Response query(String sql, Map<String,?> params)
      Executes a parameterized SurrealQL query on the database.

      For more details, check the SurrealQL documentation.

      Parameters:
      sql - the SurrealQL query to be executed
      params - a map containing parameter values to be bound to the SQL query
      Returns:
      a Response object containing the results of the query

    • queryBind

      @Deprecated public Response queryBind(String sql, Map<String,?> params)
      Deprecated.
      Since 2.0.2. Use query(String, Map) instead. Java prefers method overloading over suffixing method names. This method is intended for removal in 3.0.0.
      Executes a parameterized SurrealQL query on the database.

      For more details, check the SurrealQL documentation.

      Parameters:
      sql - the SurrealQL query to be executed
      params - a map containing parameter values to be bound to the SQL query
      Returns:
      a Response object containing the results of the query

    • create

      public <T> Value create(RecordId recordId, T content)
      Creates a record in the database with the given `RecordID` as the key and the provided content as the value.

      For more details, check the SurrealQL documentation.

      Type Parameters:
      T - the type of the content
      Parameters:
      recordId - the RecordId associated with the new record
      content - the content of the created record
      Returns:
      a new Value object initialized with the provided RecordId and content

    • create

      public <T> T create(Class<T> type, RecordId recordId, T content)
      Creates a record in the database with the given `RecordID` as the key and the provided content as the value.

      For more details, check the SurrealQL documentation.

      Parameters:
      type - The class type of the object to create
      recordId - The RecordId used with the new record
      content - The content of the created record
      Returns:
      An instance of the specified type

    • create

      @SafeVarargs public final <T> List<Value> create(String target, T... contents)
      Creates records in the database with the given table and the provided contents as the values.

      For more details, check the SurrealQL documentation.

      Type Parameters:
      T - the type of the contents
      Parameters:
      target - the target for which the records are created
      contents - the contents of the created records
      Returns:
      a list of Value objects created based on the target and contents

    • create

      @SafeVarargs public final <T> List<T> create(Class<T> type, String target, T... contents)
      Creates records in the database with the given table and the provided contents as the values.

      For more details, check the SurrealQL documentation.

      Type Parameters:
      T - the type of objects to be created
      Parameters:
      type - the class of the type to be created
      target - the target string used in the creation process
      contents - the contents to be used to create the objects
      Returns:
      a list of objects of the specified type

    • insert

      @SafeVarargs public final <T> List<Value> insert(String target, T... contents)
      Insert records in the database with the given table and the provided contents as the values.

      For more details, check the SurrealQL documentation.

      Type Parameters:
      T - the type of the contents
      Parameters:
      target - the target for which the records are inserted
      contents - the contents of the inserted records
      Returns:
      a list of Value objects inserted based on the target and contents

    • insert

      @SafeVarargs public final <T> List<T> insert(Class<T> type, String target, T... contents)
      Insert records in the database with the given table and the provided contents as the values.

      For more details, check the SurrealQL documentation.

      Type Parameters:
      T - the type of objects to be inserted
      Parameters:
      type - the class of the type to be inserted
      target - the target string used in the insertion process
      contents - the contents to be used to insert the objects
      Returns:
      a list of objects of the specified type

    • insertRelation

      public <T extends InsertRelation> Value insertRelation(String target, T content)
      Inserts a relation to the specified table using the provided content.

      For more details, check the SurrealQL documentation.

      Type Parameters:
      T - a type that extends InsertRelation
      Parameters:
      target - the table where the relation is to be inserted
      content - the content to insert as the relation
      Returns:
      a Value object representing the inserted relation

    • insertRelation

      public <T extends InsertRelation> T insertRelation(Class<T> type, String target, T content)
      Inserts a relation of the specified type and table with the provided content.

      For more details, check the SurrealQL documentation.

      Type Parameters:
      T - the type of the relation that extends InsertRelation
      Parameters:
      type - the class object of the type T
      target - the target identifier for the relation
      content - the content to be inserted in the relation
      Returns:
      the inserted relation of type T

    • insertRelations

      @SafeVarargs public final <T extends InsertRelation> List<Value> insertRelations(String target, T... contents)
      Inserts relations into the specified table with the provided contents.

      For more details, check the SurrealQL documentation.

      Type Parameters:
      T - the type of the insert relation
      Parameters:
      target - the table into which the relations will be inserted
      contents - the contents of the relations to be inserted
      Returns:
      a list of values representing the result of the insert operation

    • insertRelations

      @SafeVarargs public final <T extends InsertRelation> List<T> insertRelations(Class<T> type, String target, T... contents)
      Inserts multiple relations of a specified type into the target.

      For more details, check the SurrealQL documentation.

      Type Parameters:
      T - the type of InsertRelation
      Parameters:
      type - the class type of the InsertRelation
      target - the table in which the relations are to be inserted
      contents - the array of InsertRelation objects to be inserted
      Returns:
      a list of inserted relations of the specified type

    • relate

      public Value relate(RecordId from, String table, RecordId to)
      Establishes a relation between two records identified by `from` and `to` within a specified table.

      For more details, check the SurrealQL documentation.

      Parameters:
      from - the record identifier from which the relation originates
      table - the name of the table where the relation will be established
      to - the record identifier to which the relation points
      Returns:
      a new Value instance representing the relation

    • relate

      public <T extends Relation> T relate(Class<T> type, RecordId from, String table, RecordId to)
      Establishes and retrieves a relation of a specified type between two records.

      For more details, check the SurrealQL documentation.

      Type Parameters:
      T - The type of the relation extending Relation.
      Parameters:
      type - The class type of the relation.
      from - The starting record of the relation.
      table - The name of the table that holds the relation.
      to - The ending record of the relation.
      Returns:
      The established relation of the specified type.

    • relate

      public <T> Value relate(RecordId from, String table, RecordId to, T content)
      Establishes a relationship between two records within a specified table, attaching the provided content to this relationship.

      For more details, check the SurrealQL documentation.

      Type Parameters:
      T - the type of the content associated with the relation
      Parameters:
      from - The record ID that the relationship starts from.
      table - The table in which the relationship is being created.
      to - The record ID that the relationship points to.
      content - The content to attach to the relationship.
      Returns:
      A Value object representing the newly created relationship.

    • relate

      public <R extends Relation, T> R relate(Class<R> type, RecordId from, String table, RecordId to, T content)
      Establishes a relation between two records and retrieves it based on the specified relation type.

      For more details, check the SurrealQL documentation.

      Type Parameters:
      R - the type of the relation
      T - the type of the content associated with the relation
      Parameters:
      type - the class of the relation type
      from - the record identifier of the source record
      table - the name of the table where the relation is to be established
      to - the record identifier of the target record
      content - the content to be associated with the relation
      Returns:
      the established relation of the specified type

    • update

      public <T> Value update(RecordId recordId, UpType upType, T content)
      Updates the value of a record with the specified content and update type.

      For more details, check the SurrealQL documentation.

      Type Parameters:
      T - The type of the content to be updated.
      Parameters:
      recordId - The RecordId of the record to be updated.
      upType - The type of update to be performed.
      content - The new content to set for the specified record.
      Returns:
      A Value object representing the updated value.

    • update

      public <T> Value update(RecordIdRange range, UpType upType, T content)
      Updates all records in the given record ID range with the given content.
      Parameters:
      range - the table and optional start/end bounds
      upType - CONTENT, MERGE, etc.
      content - the update content
      Returns:
      the first updated value (range updates return one result per updated record; this returns the first)

    • update

      public <T> T update(Class<T> type, RecordId recordId, UpType upType, T content)
      Updates a record of the specified type and returns the updated record.

      For more details, check the SurrealQL documentation.

      Type Parameters:
      T - the type of the record
      Parameters:
      type - the class type of the record to be updated
      recordId - the identifier of the record to be updated
      upType - the type of update operation to be performed
      content - the new content to update the record with
      Returns:
      the updated record of the specified type

    • update

      public <T> Iterator<Value> update(String target, UpType upType, T content)
      Updates the table with the given content based on the specified update type.

      For more details, check the SurrealQL documentation.

      Type Parameters:
      T - the type of the content to be used for the update
      Parameters:
      target - the table to be updated
      upType - the type of update operation to be performed
      content - the content to update the target with
      Returns:
      an Iterator of Value objects reflecting the updated state of the target

    • update

      public <T> Iterator<Value> update(String[] targets, UpType upType, T content)
      Updates the specified tables with the given content.

      For more details, check the SurrealQL documentation.

      Type Parameters:
      T - the type of the content
      Parameters:
      targets - an array of strings representing the table identifiers to be updated
      upType - the type of update operation to be performed
      content - the content to update the targets with; the content can be of any type
      Returns:
      an Iterator of Value objects representing the updated values

    • update

      public <T> Iterator<T> update(Class<T> type, String target, UpType upType, T content)
      Updates the specified table with the provided content and returns an iterator for the updated values.

      For more details, check the SurrealQL documentation.

      Type Parameters:
      T - the type of the content and the type parameter for the iterator
      Parameters:
      type - the class type of the content
      target - the table to be updated
      upType - the type of update operation to be performed
      content - the content to update the target with
      Returns:
      an iterator over the updated values

    • update

      public <T> Iterator<T> update(Class<T> type, String[] targets, UpType upType, T content)
      Updates the specified tables with the given content and returns an iterator over the updated elements of the specified type.

      For more details, check the SurrealQL documentation.

      Type Parameters:
      T - The type of the elements being updated.
      Parameters:
      type - The class type of the elements to be updated.
      targets - An array of table identifiers to be updated.
      upType - The type of update operation to be performed.
      content - The content to update the targets with.
      Returns:
      An iterator over the updated elements of the specified type.

    • updateSync

      public <T> Iterator<Value> updateSync(String target, UpType upType, T content)
      Updates the specified table with the provided content.

      For more details, check the SurrealQL documentation.

      Type Parameters:
      T - The type of the content to be synchronized.
      Parameters:
      target - The table identifier to be updated.
      upType - The type of update to be performed, represented by an UpType object.
      content - The content to update the target with.
      Returns:
      A thread-safe Iterator of Value objects that reflects the updated state.

    • updateSync

      public <T> Iterator<Value> updateSync(String[] targets, UpType upType, T content)
      Updates the tables using the provided content and update type.

      For more details, check the SurrealQL documentation.

      Type Parameters:
      T - the type of the content being updated
      Parameters:
      targets - an array of strings representing the tables to be updated
      upType - an instance of UpType indicating the type of update to be performed
      content - the content to be used for the update, which will be converted to a Value
      Returns:
      a thread-safe iterator over the updated Value objects

    • updateSync

      public <T> Iterator<T> updateSync(Class<T> type, String target, UpType upType, T content)
      Updates the table with the provided content. The updated resource is then returned as a thread-safe iterator of the specified type.

      For more details, check the SurrealQL documentation.

      Type Parameters:
      T - the type of the content being updated
      Parameters:
      type - the class type of the elements that the returned iterator will contain
      target - the identifier of the table resource to be updated
      upType - the type of update operation to be performed
      content - the data to update the target resource with
      Returns:
      a thread-safe iterator of the specified type containing the updated resource

    • updateSync

      public <T> Iterator<T> updateSync(Class<T> type, String[] targets, UpType upType, T content)
      Updates the provided tables with the provided content and returns an iterator for the updated values.

      For more details, check the SurrealQL documentation.

      Type Parameters:
      T - the type of the content being updated
      Parameters:
      type - the class type of the content
      targets - an array of target identifiers to be updated
      upType - the type of update to be performed
      content - the content to be used for the update
      Returns:
      a thread-safe iterator for the updated values

    • upsert

      public <T> Value upsert(RecordId recordId, UpType upType, T content)
      Inserts a new record or updates an existing record with the given content.

      For more details, check the SurrealQL documentation.

      Type Parameters:
      T - The type of the content.
      Parameters:
      recordId - The record identifier.
      upType - The update type specifying how to handle the upsert.
      content - The content to be inserted or updated.
      Returns:
      The resulting value after the upsert operation.

    • upsert

      public <T> Value upsert(RecordIdRange range, UpType upType, T content)
      Upserts all records in the given record ID range with the given content.
      Parameters:
      range - the table and optional start/end bounds
      upType - CONTENT, MERGE, etc.
      content - the upsert content
      Returns:
      the first upserted value

    • upsert

      public <T> T upsert(Class<T> type, RecordId recordId, UpType upType, T content)
      Upserts a record and returns the updated or inserted entity.

      For more details, check the SurrealQL documentation.

      Type Parameters:
      T - The type of the entity to be upserted.
      Parameters:
      type - The class type of the entity.
      recordId - The record identifier.
      upType - The type of the update.
      content - The content of the entity to be upserted.
      Returns:
      The upserted entity of the specified type.

    • upsert

      public <T> Iterator<Value> upsert(String target, UpType upType, T content)
      Performs an upsert operation on the specified table with the provided content. The operation type is determined by the UpType enumeration.

      For more details, check the SurrealQL documentation.

      Type Parameters:
      T - The type of the content to be upserted.
      Parameters:
      target - The target on which the upsert operation is to be performed.
      upType - The type of upsert operation to be executed.
      content - The content to be upserted.
      Returns:
      An iterator over the values resulting from the upsert operation.

    • upsert

      public <T> Iterator<Value> upsert(String[] targets, UpType upType, T content)
      Inserts or updates values in the given tables.

      For more details, check the SurrealQL documentation.

      Type Parameters:
      T - The type of the content to upsert.
      Parameters:
      targets - The array of tables to upsert values.
      upType - The type specifying the upserting strategy to use.
      content - The content to be inserted or updated.
      Returns:
      An iterator over the upserted values.

    • upsert

      public <T> Iterator<T> upsert(Class<T> type, String target, UpType upType, T content)
      Inserts or updates a record of the specified type with the given content.

      For more details, check the SurrealQL documentation.

      Type Parameters:
      T - the type of the object to be upserted.
      Parameters:
      type - the Class object representing the type of the object.
      target - the table identifier where the records should be upserted.
      upType - the type of upsert operation to perform.
      content - the content of the object to be upserted.
      Returns:
      an iterator of the type T containing the results of the upsert operation.

    • upsert

      public <T> Iterator<T> upsert(Class<T> type, String[] targets, UpType upType, T content)
      Updates or inserts the provided content based on the specified tables and update type.

      For more details, check the SurrealQL documentation.

      Type Parameters:
      T - The type of the content to upsert.
      Parameters:
      type - the Class object representing the type of the object.
      targets - An array of target identifiers for the upsert operation.
      upType - The type of the upsert operation specifying how to merge the content.
      content - The content to be upserted.
      Returns:
      An iterator over the result of the upsert operation.

    • upsertSync

      public <T> Iterator<Value> upsertSync(String target, UpType upType, T content)
      Inserts or updates the table with the provided content and returns a thread-safe iterator over the resulting values.

      For more details, check the SurrealQL documentation.

      Type Parameters:
      T - the type of the content to be upserted
      Parameters:
      target - the target identifier where the content will be upserted
      upType - the type of upsert operation
      content - the content to be upserted
      Returns:
      a thread-safe iterator over the resulting values after the upsert operation

    • upsertSync

      public <T> Iterator<Value> upsertSync(String[] targets, UpType upType, T content)
      Performs an upsert (update or insert) operation on the specified tables.

      For more details, check the SurrealQL documentation.

      Type Parameters:
      T - the type of the record to upsert
      Parameters:
      targets - an array of target identifiers to perform the upsert operation on
      upType - the type of upsert operation to perform
      content - the content to be upserted
      Returns:
      a thread-safe Iterator of the resulting values from the upsert operation

    • upsertSync

      public <T> Iterator<T> upsertSync(Class<T> type, String target, UpType upType, T content)
      Inserts or updates a record and returns an iterator over the result.

      For more details, check the SurrealQL documentation.

      Type Parameters:
      T - the type of the record to upsert
      Parameters:
      type - the class representing the type of the record
      target - the target location for the upsert operation
      upType - the type of the upsert operation
      content - the content of the record to be upserted
      Returns:
      a thread-safe iterator over the upserted record

    • upsertSync

      public <T> Iterator<T> upsertSync(Class<T> type, String[] targets, UpType upType, T content)
      Performs an upsert operation with the specified content on the given tables.

      For more details, check the SurrealQL documentation.

      Type Parameters:
      T - The type of the content being upserted and returned iterator's elements.
      Parameters:
      type - The class type of the content.
      targets - The array of table identifiers on which to perform the upsert operation.
      upType - The type of upsert operation to be performed.
      content - The content to be upserted.
      Returns:
      A thread-safe iterator over the upserted content of the specified type.

    • select

      public Optional<Value> select(RecordId recordId)
      Selects a record by its RecordId and retrieves the corresponding Value.

      For more details, check the SurrealQL documentation.

      Parameters:
      recordId - the unique identifier of the record to be selected
      Returns:
      an Optional containing the Value if the record is found, or an empty Optional if not found

    • select

      public <T> Optional<T> select(Class<T> type, RecordId recordId)
      Selects an instance of the specified type from a record identified by the given RecordId.

      For more details, check the SurrealQL documentation.

      Type Parameters:
      T - the type of the instance to be selected
      Parameters:
      type - the class type of the instance to be selected
      recordId - the unique identifier of the record from which to select the instance
      Returns:
      an Optional containing the selected instance of the specified type if present, otherwise an empty Optional

    • select

      public List<Value> select(RecordId... recordIds)
      Selects values based on the provided RecordIds.

      For more details, check the SurrealQL documentation.

      Parameters:
      recordIds - an array of RecordId objects to be used in the selection.
      Returns:
      a list of Value objects corresponding to the selected RecordIds.

    • select

      public <T> List<T> select(Class<T> type, RecordId... recordIds)
      Selects and retrieves a list of objects of the specified type based on the given record IDs.

      For more details, check the SurrealQL documentation.

      Type Parameters:
      T - the type of objects to be retrieved
      Parameters:
      type - the Class object of the type to be retrieved
      recordIds - an array of RecordId instances identifying the records to be selected
      Returns:
      a list of objects of the specified type corresponding to the given record IDs

    • select

      public List<Value> select(RecordIdRange range)
      Selects all records in the given record ID range.
      Parameters:
      range - the table and optional start/end bounds (null = unbounded)
      Returns:
      list of values for records in the range

    • select

      public <T> List<T> select(Class<T> type, RecordIdRange range)
      Selects records in the given range and maps them to the specified type.
      Type Parameters:
      T - the type of objects to be retrieved
      Parameters:
      type - the class of the type
      range - the table and optional start/end bounds
      Returns:
      list of objects of the specified type

    • select

      public Iterator<Value> select(String targets)
      Selects and returns an iterator over the values corresponding to the given targets.

      For more details, check the SurrealQL documentation.

      Parameters:
      targets - A string representing the targets to be selected.
      Returns:
      An iterator over the values corresponding to the specified targets.

    • selectSync

      public Iterator<Value> selectSync(String targets)
      Selects and returns a thread-safe iterator to traverse values associated with the given targets.

      For more details, check the SurrealQL documentation.

      Parameters:
      targets - The specified targets for which values need to be selected.
      Returns:
      A thread-safe iterator to traverse the values associated with the specified targets.

    • select

      public <T> Iterator<T> select(Class<T> type, String targets)
      Selects and retrieves an iterator of specified type for given targets.

      For more details, check the SurrealQL documentation.

      Type Parameters:
      T - The type of objects to be selected.
      Parameters:
      type - The class type of the objects to be selected.
      targets - A string specifying the targets to select from.
      Returns:
      An iterator of the specified type for the selected targets.

    • selectSync

      public <T> Iterator<T> selectSync(Class<T> type, String targets)
      Selects and returns a thread-safe iterator over a collection of objects of the specified type from the given targets.

      For more details, check the SurrealQL documentation.

      Type Parameters:
      T - the type of objects to be iterated over
      Parameters:
      type - the class of the type of objects to be selected
      targets - the targets from which to select objects
      Returns:
      a thread-safe iterator over a collection of objects of the specified type

    • delete

      public void delete(RecordId recordId)
      Deletes a record identified by the provided RecordId.

      For more details, check the SurrealQL documentation.

      Parameters:
      recordId - the identifier of the record to be deleted

    • delete

      public void delete(RecordId... recordIds)
      Deletes the specified records.

      For more details, check the SurrealQL documentation.

      Parameters:
      recordIds - An array of RecordId objects representing the records to be deleted.

    • delete

      public void delete(RecordIdRange range)
      Deletes all records in the given record ID range.
      Parameters:
      range - the table and optional start/end bounds

    • delete

      public void delete(String target)
      Deletes the specified target.

      For more details, check the SurrealQL documentation.

      Parameters:
      target - the name of the target to be deleted