Class: SurrealDB::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/surrealdb/client.rb

Overview

Main client for interacting with SurrealDB.

Provides a unified API across WebSocket and HTTP transports, selected automatically based on the connection URL scheme.

Examples:

client = SurrealDB::Client.new("ws://localhost:8000")
client.connect
client.use("test", "test")
client.("user" => "root", "pass" => "root")
results = client.select("users")
client.close

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(url, **options) ⇒ Client

Returns a new instance of Client.

Parameters:

  • url (String) —

    connection URL (ws://, wss://, http://, https://)

  • options (Hash) —

    connection options (:timeout, etc.)



24
25
26
27
28
 
# File 'lib/surrealdb/client.rb', line 24

def initialize(url, **options)
  @url = url
  @options = options
  @connection = build_connection(url, **options)
end

Instance Attribute Details

#connection ⇒ Connections::Base (readonly)

Returns:



20
21
22
 
# File 'lib/surrealdb/client.rb', line 20

def connection
  @connection
end

Instance Method Details

#attach ⇒ String

Attaches a new session to the connection.

Returns:

  • (String) —

    session ID



287
288
289
290
 
# File 'lib/surrealdb/client.rb', line 287

def attach
  require_websocket!('sessions')
  @connection.send_request(Protocol::Methods::ATTACH)
end

#authenticate(token) ⇒ void

This method returns an undefined value.

Authenticates with an existing JWT token.

Parameters:

  • token (String) 


77
78
79
 
# File 'lib/surrealdb/client.rb', line 77

def authenticate(token)
  @connection.send_request(Protocol::Methods::AUTHENTICATE, [token])
end

#begin_transaction ⇒ void

This method returns an undefined value.

Begins a transaction on the current session.



302
303
304
305
 
# File 'lib/surrealdb/client.rb', line 302

def begin_transaction
  require_websocket!('transactions')
  @connection.send_request(Protocol::Methods::BEGIN_TXN)
end

#cancel ⇒ void

This method returns an undefined value.

Cancels (rolls back) the current transaction.



316
317
318
319
 
# File 'lib/surrealdb/client.rb', line 316

def cancel
  require_websocket!('transactions')
  @connection.send_request(Protocol::Methods::CANCEL)
end

#close ⇒ void

This method returns an undefined value.

Closes the connection.



39
40
41
 
# File 'lib/surrealdb/client.rb', line 39

def close
  @connection.close
end

#commit ⇒ void

This method returns an undefined value.

Commits the current transaction.



309
310
311
312
 
# File 'lib/surrealdb/client.rb', line 309

def commit
  require_websocket!('transactions')
  @connection.send_request(Protocol::Methods::COMMIT)
end

#connect ⇒ self

Opens the connection to SurrealDB.

Returns:

  • (self) 


32
33
34
35
 
# File 'lib/surrealdb/client.rb', line 32

def connect
  @connection.connect
  self
end

#connected? ⇒ Boolean

Returns:

  • (Boolean) 


44
45
46
 
# File 'lib/surrealdb/client.rb', line 44

def connected?
  @connection.connected?
end

#create(resource, data = nil) ⇒ Hash

Creates a new record.

Parameters:

  • resource (String, RecordID, Table)
  • data (Hash, nil) (defaults to: nil) —

    record content

Returns:

  • (Hash) —

    created record



118
119
120
121
122
 
# File 'lib/surrealdb/client.rb', line 118

def create(resource, data = nil)
  params = [resource_param(resource)]
  params << data unless data.nil?
  @connection.send_request(Protocol::Methods::CREATE, params)
end

#delete(resource) ⇒ Object

Deletes a record or all records from a table.

Parameters:

Returns:

  • (Object) —

    deleted record(s)



175
176
177
 
# File 'lib/surrealdb/client.rb', line 175

def delete(resource)
  @connection.send_request(Protocol::Methods::DELETE, [resource_param(resource)])
end

#detach(session_id) ⇒ void

This method returns an undefined value.

Detaches a session from the connection.

Parameters:

  • session_id (String) 


295
296
297
298
 
# File 'lib/surrealdb/client.rb', line 295

def detach(session_id)
  require_websocket!('sessions')
  @connection.send_request(Protocol::Methods::DETACH, [session_id])
end

#export_data ⇒ String

Exports the database as SurrealQL.

Returns:

  • (String) —

    exported data



265
266
267
 
# File 'lib/surrealdb/client.rb', line 265

def export_data
  @connection.send_request(Protocol::Methods::EXPORT)
end

#import_data(content) ⇒ Object

Imports SurrealQL data or ML model data into the database.

Parameters:

  • content (String) —

    SurrealQL or ML content to import

Returns:

  • (Object) 


259
260
261
 
# File 'lib/surrealdb/client.rb', line 259

def import_data(content)
  @connection.send_request(Protocol::Methods::IMPORT, [content])
end

#info ⇒ Hash?

Returns info about the current session.

Returns:

  • (Hash, nil) 


279
280
281
 
# File 'lib/surrealdb/client.rb', line 279

def info
  @connection.send_request(Protocol::Methods::INFO)
end

#insert(table, data) ⇒ Array

Inserts one or more records into a table.

Parameters:

  • table (String, Table) —

    table name

  • data (Hash, Array<Hash>) —

    record(s) to insert

Returns:

  • (Array) —

    inserted records



128
129
130
 
# File 'lib/surrealdb/client.rb', line 128

def insert(table, data)
  @connection.send_request(Protocol::Methods::INSERT, [table_param(table), data])
end

#insert_relation(table, data) ⇒ Array

Inserts a relation record.

Parameters:

  • table (String, Table) —

    relation table name

  • data (Hash) —

    relation data (must include :in and :out)

Returns:

  • (Array) —

    inserted relation records



136
137
138
 
# File 'lib/surrealdb/client.rb', line 136

def insert_relation(table, data)
  @connection.send_request(Protocol::Methods::INSERT_RELATION, [table_param(table), data])
end

#invalidate ⇒ void

This method returns an undefined value.

Invalidates the current session.



83
84
85
 
# File 'lib/surrealdb/client.rb', line 83

def invalidate
  @connection.send_request(Protocol::Methods::INVALIDATE)
end

#kill(live_query_id) ⇒ void

This method returns an undefined value.

Kills a live query.

Parameters:

  • live_query_id (String) 


248
249
250
251
252
 
# File 'lib/surrealdb/client.rb', line 248

def kill(live_query_id)
  require_live_queries!
  @connection.remove_notification_handler(live_query_id.to_s)
  @connection.send_request(Protocol::Methods::KILL, [live_query_id])
end

#live(resource, diff: false) ⇒ String

Starts a live query on a table (WebSocket only).

Parameters:

  • resource (String, Table) —

    table name

  • diff (Boolean) (defaults to: false) —

    whether to receive diffs instead of full records

Returns:

  • (String) —

    live query UUID



231
232
233
234
 
# File 'lib/surrealdb/client.rb', line 231

def live(resource, diff: false)
  require_live_queries!
  @connection.send_request(Protocol::Methods::LIVE, [table_param(resource), diff])
end

#merge(resource, data) ⇒ Object

Deep-merges data into a record.

Parameters:

  • resource (String, RecordID, Table)
  • data (Hash) —

    data to merge

Returns:

  • (Object) —

    merged record(s)



160
161
162
 
# File 'lib/surrealdb/client.rb', line 160

def merge(resource, data)
  @connection.send_request(Protocol::Methods::MERGE, [resource_param(resource), data])
end

#patch(resource, patches) ⇒ Object

Applies JSON Patch operations to a record.

Parameters:

  • resource (String, RecordID, Table)
  • patches (Array<Hash>) —

    patch operations

Returns:

  • (Object) —

    patched record(s)



168
169
170
 
# File 'lib/surrealdb/client.rb', line 168

def patch(resource, patches)
  @connection.send_request(Protocol::Methods::PATCH, [resource_param(resource), patches])
end

#query(sql, vars = {}) ⇒ Array

Executes a SurrealQL query.

Parameters:

  • sql (String) —

    SurrealQL statement(s)

  • vars (Hash) (defaults to: {}) —

    query variables

Returns:

  • (Array) —

    array of result sets (one per statement)



197
198
199
200
201
 
# File 'lib/surrealdb/client.rb', line 197

def query(sql, vars = {})
  params = [sql]
  params << vars unless vars.empty?
  @connection.send_request(Protocol::Methods::QUERY, params)
end

#query_raw(sql, vars = {}) ⇒ Array<QueryResult>

Executes a SurrealQL query and returns structured per-statement results. Unlike #query, this returns QueryResult objects with status, timing, and per-statement error information.

Parameters:

  • sql (String) —

    SurrealQL statement(s)

  • vars (Hash) (defaults to: {}) —

    query variables

Returns:



209
210
211
212
213
214
 
# File 'lib/surrealdb/client.rb', line 209

def query_raw(sql, vars = {})
  params = [sql]
  params << vars unless vars.empty?
  raw = @connection.send_request(Protocol::Methods::QUERY, params)
  Array(raw).map { |stmt| QueryResult.from_response(stmt) }
end

#relate(from, relation, to, data = nil) ⇒ Object

Creates a graph relation between two records.

Parameters:

  • from (String, RecordID) —

    source record

  • relation (String) —

    relation table

  • to (String, RecordID) —

    target record

  • data (Hash, nil) (defaults to: nil) —

    relation content

Returns:

  • (Object) —

    created relation



185
186
187
188
189
 
# File 'lib/surrealdb/client.rb', line 185

def relate(from, relation, to, data = nil)
  params = [resource_param(from), relation, resource_param(to)]
  params << data unless data.nil?
  @connection.send_request(Protocol::Methods::RELATE, params)
end

#run(function_name, *args, version: nil) ⇒ Object

Runs a SurrealDB function.

Parameters:

  • function_name (String)
  • args (Array) —

    function arguments

  • version (String, nil) (defaults to: nil) —

    optional function version

Returns:

  • (Object) 


221
222
223
 
# File 'lib/surrealdb/client.rb', line 221

def run(function_name, *args, version: nil)
  @connection.send_request(Protocol::Methods::RUN, [function_name, version, args])
end

#select(resource) ⇒ Array, Hash

Selects all records from a table, or a single record by ID.

Parameters:

  • resource (String, RecordID, Table) —

    table name, "table:id", or RecordID

Returns:

  • (Array, Hash) —

    records



110
111
112
 
# File 'lib/surrealdb/client.rb', line 110

def select(resource)
  @connection.send_request(Protocol::Methods::SELECT, [resource_param(resource)])
end

#send_rpc(method, params = []) ⇒ Object

Sends an arbitrary RPC method call. Useful as an escape hatch for server methods not yet wrapped by the SDK.

Parameters:

  • method (String) —

    RPC method name

  • params (Array) (defaults to: []) —

    method parameters

Returns:

  • (Object) —

    decoded result



328
329
330
 
# File 'lib/surrealdb/client.rb', line 328

def send_rpc(method, params = [])
  @connection.send_request(method, params)
end

#set(key, value) ⇒ void Also known as: let

This method returns an undefined value.

Sets a connection-scoped variable.

Parameters:

  • key (String)
  • value (Object) 


93
94
95
 
# File 'lib/surrealdb/client.rb', line 93

def set(key, value)
  @connection.send_request(Protocol::Methods::LET, [key, value])
end

#signin(credentials = {}) ⇒ String, Hash

Signs in to SurrealDB.

Parameters:

  • credentials (Hash) (defaults to: {}) —

    authentication credentials (string keys)

Returns:

  • (String, Hash) —

    JWT token or tokens hash



63
64
65
 
# File 'lib/surrealdb/client.rb', line 63

def (credentials = {})
  @connection.send_request(Protocol::Methods::SIGNIN, [credentials])
end

#signup(credentials = {}) ⇒ String, Hash

Signs up a new user.

Parameters:

  • credentials (Hash) (defaults to: {}) —

    signup credentials (string keys)

Returns:

  • (String, Hash) —

    JWT token or tokens hash



70
71
72
 
# File 'lib/surrealdb/client.rb', line 70

def (credentials = {})
  @connection.send_request(Protocol::Methods::SIGNUP, [credentials])
end

#subscribe(live_query_id) {|Hash| ... } ⇒ void

This method returns an undefined value.

Subscribes to live query notifications.

Parameters:

  • live_query_id (String) —

    UUID from #live

Yields:

  • (Hash) —

    notification with :action and :result keys



240
241
242
243
 
# File 'lib/surrealdb/client.rb', line 240

def subscribe(live_query_id, &block)
  require_live_queries!
  @connection.on_notification(live_query_id.to_s, block)
end

#unset(key) ⇒ void

This method returns an undefined value.

Removes a connection-scoped variable.

Parameters:

  • key (String) 


101
102
103
 
# File 'lib/surrealdb/client.rb', line 101

def unset(key)
  @connection.send_request(Protocol::Methods::UNSET, [key])
end

#update(resource, data) ⇒ Object

Replaces a record or all records in a table.

Parameters:

  • resource (String, RecordID, Table)
  • data (Hash) —

    replacement content

Returns:

  • (Object) —

    updated record(s)



144
145
146
 
# File 'lib/surrealdb/client.rb', line 144

def update(resource, data)
  @connection.send_request(Protocol::Methods::UPDATE, [resource_param(resource), data])
end

#upsert(resource, data) ⇒ Object

Upserts a record (insert or update).

Parameters:

  • resource (String, RecordID, Table)
  • data (Hash) —

    record content

Returns:

  • (Object) —

    upserted record(s)



152
153
154
 
# File 'lib/surrealdb/client.rb', line 152

def upsert(resource, data)
  @connection.send_request(Protocol::Methods::UPSERT, [resource_param(resource), data])
end

#use(namespace, database) ⇒ void

This method returns an undefined value.

Selects the namespace and database to use.

Parameters:

  • namespace (String)
  • database (String) 


54
55
56
 
# File 'lib/surrealdb/client.rb', line 54

def use(namespace, database)
  @connection.send_request(Protocol::Methods::USE, [namespace, database])
end

#version ⇒ String

Returns the SurrealDB server version.

Returns:

  • (String) 


273
274
275
 
# File 'lib/surrealdb/client.rb', line 273

def version
  @connection.send_request(Protocol::Methods::VERSION)
end