ADD relate method

- fix run function
- add example for db
- add relate rpc method

README.md

@@ -1,6 +1,6 @@
 # README #
 
-Surrealist is a Python tool to work with awesome [SurrealDB](https://docs.surrealdb.com/docs/intro) (support for latest version 2.0.1)
+Surrealist is a Python tool to work with awesome [SurrealDB](https://docs.surrealdb.com/docs/intro) (support for latest version 2.0.2)
 
 It is **synchronous** and **unofficial**, so if you need async AND/OR official client, go [here](https://github.com/surrealdb/surrealdb.py)
 
@@ -11,7 +11,7 @@ Works and tested on Ubuntu, macOS, Windows 10, can use python 3.8+ (including py
  * only one small dependency (websocket-client), no need to pull a lot of libraries to your project
  * fully documented
  * well tested (on the latest Ubuntu, macOS and Windows 10)
- * fully compatible with the latest version of SurrealDB (2.0.1), including [live queries](https://surrealdb.com/products/lq) and [change feeds](https://surrealdb.com/products/cf)
+ * fully compatible with the latest version of SurrealDB (2.0.2), including [live queries](https://surrealdb.com/products/lq) and [change feeds](https://surrealdb.com/products/cf)
  * debug mode to see all that goes in and out if you need (using standard logging)
  * iterator to handle big select queries
  * QL-builder to explore, generate and use SurrealDB queries (explain, transaction etc.)
@@ -37,11 +37,10 @@ Surreal DB version 1.5.3 or earlier. Please consider table to choose a version:
 |    Surrealist version     |     1.0.0      | 0.5.3   | 0.4.2+   | 0.3.1+   | 0.2.10+  | 0.2.3+   |
 |      Python versions      |    3.8-3.12    |     3.8-3.12    | 3.8-3.12 | 3.8-3.12 | 3.8-3.12 | 3.8-3.12 |
 
-
+A good place to start is connect examples [here](https://github.com/kotolex/surrealist/tree/master/examples/connect.py)
 
 You can find a lot of examples [here](https://github.com/kotolex/surrealist/tree/master/examples)
 
-A good place to start is connect examples [here](https://github.com/kotolex/surrealist/tree/master/examples/connect.py)
 
 ## Transports ##
 First of all, you should know that SurrealDB can work with websocket or http "transports", we chose to support both transports here, 

ReleaseNotes.md

@@ -1,9 +1,10 @@
 ## Release Notes ##
-**Version 1.0.1 (compatible with SurrealDB version 2.0.2+):**
-- add run and run_function for Database (https://surrealdb.com/docs/surrealdb/integration/rpc#run)
+**Version 1.0.1 (compatible with SurrealDB version 2.0.2):**
+- add run method for connections and run_function for Database (https://surrealdb.com/docs/surrealdb/integration/rpc#run)
 - add insert_relation method for connections (https://surrealdb.com/docs/surrealdb/integration/rpc#insert_relation)
 - add version method for connections (https://surrealdb.com/docs/surrealdb/integration/rpc#version)
 - add info method for connections (https://surrealdb.com/docs/surrealdb/integration/rpc#info)
+- add relate method for connections (https://surrealdb.com/docs/surrealdb/integration/rpc#relate)
 - minor fixes for docs and examples
 
 **Version 1.0.0 (compatible with SurrealDB version 2.0.0+):**

examples/surreal_ql/database.py

@@ -16,6 +16,9 @@
     print(db.person)  # Table(name=person)
     print(db.table("person"))  # Table(name=person)
 
+    # database can run built-in functions
+    print(db.run_function("math::abs", None, [-100]).result)  # returns 100 (math::abs(-100))
+
     # database can use RETURN statement
     # Refer to: https://docs.surrealdb.com/docs/surrealql/statements/return
     print(db.returns("math::abs(-100)"))  # RETURN math::abs(-100);

src/surrealist/connections/connection.py

@@ -402,13 +402,15 @@ def run(self, func_name: str, version: Optional[str] = None, args: Optional[List
         ml:: for machine learning models.
         :param version: optional parameter, the version of the function or model to execute. When using a machine
         learning model (prefixed with ml::), the version parameter is required.
-        :param args: The arguments to pass to the function or model.
+        :param args: The list of arguments to pass to the function or model.
         :return: result of request
         """
         data = {"method": "run", "params": [func_name]}
         if version is not None:
             data["params"].append(version)
         if args is not None:
+            if len(data["params"]) == 1:
+                data["params"].append(None)
             data["params"].append(args)
         logger.info("Operation: RUN. Function: %s, version: %s, args: %s", crop_data(func_name), version, args)
         result = self._use_rpc(data)
@@ -715,6 +717,31 @@ def query(self, query: str, variables: Optional[Dict] = None) -> SurrealResult:
         result.query = params[0] if len(params) == 1 else params
         return result
 
+    @connected
+    def relate(self, relate_to: str, relation_table: str, relate_from: str,
+               data: Optional[Dict] = None) -> SurrealResult:
+        """
+        This method relates two records with a specified relation
+
+        Refer to: https://surrealdb.com/docs/surrealdb/integration/rpc#relate
+
+        Examples:
+        connection.relate("person:john", "knows", "person:jane")
+
+        :param relate_to: The record to relate to
+        :param relation_table: name of the relation table
+        :param relate_from: The record to relate from
+        :param data: dict containing the data for the new record
+        :return: result of request
+        """
+        full_data = {"method": "relate", "params": [relate_to, relation_table, relate_from]}
+        if data is not None:
+            full_data["params"].append(data)
+        logger.info("Operation: RELATE. Relate_to: %s, relation_table: %s, relate_from: %s, data: %s", relate_to,
+                    relation_table, relate_from, crop_data(str(data)))
+        result = self._use_rpc(full_data)
+        return result
+
     @abstractmethod
     def import_data(self, path) -> SurrealResult:
         """

src/surrealist/ql/database.py

@@ -580,6 +580,5 @@ def run_function(self, function_name: str, version: Optional[str] = None,
         """
         return self._connection.run(function_name, version=version, args=args)
 
-
     def __repr__(self):
         return f"Database(namespace={self._namespace}, name={self._database}, connected={self.is_connected()})"

tests/integration_tests/test_http_connection.py

@@ -500,6 +500,13 @@ def test_version(self):
             res = connection.version()
             self.assertFalse(res.is_error(), res)
 
+    def test_relate(self):
+        surreal = Surreal(URL, credentials=('root', 'root'), use_http=True)
+        with surreal.connect() as connection:
+            connection.use("test", "test")
+            res = connection.relate("person:john", "knows", "person:jane")
+            self.assertFalse(res.is_error(), res)
+
 
 if __name__ == '__main__':
     main()

tests/integration_tests/test_ws_connection.py

@@ -510,6 +510,13 @@ def test_version(self):
             res = connection.version()
             self.assertFalse(res.is_error(), res)
 
+    def test_relate(self):
+        surreal = Surreal(URL, credentials=('root', 'root'))
+        with surreal.connect() as connection:
+            connection.use("test", "test")
+            res = connection.relate("person:tobie", "knows", "person:micha", {"since": "2024-09-15T12:34:56Z"})
+            self.assertFalse(res.is_error(), res)
+
 
 if __name__ == '__main__':
     main()

tests/integration_tests/utils.py

@@ -23,6 +23,7 @@
 with db.connect() as connection:
     connection.use("test", "test")
     connection.import_data(file_path)
+    connection.query("DEFINE CONFIG GRAPHQL AUTO")  # enable graphql
 
 
 def get_random_series(length: int) -> str: