Create table from SQL query involving tables in the same project.

README.md

@@ -74,6 +74,33 @@ External CSV files can be imported into a table:
 table = dataset.create_table_from('https://www.data.gouv.fr/fr/datasets/r/c0f59f00-3ab2-4f31-8a05-d317b43e9055', sep=';')
 df = table.aspandas()
 ```
+
+## Creation of a table from a query
+The tables from different datasets can be combined in a query.
+
+```python
+import pandas as pd
+
+dataset1 = project.create_dataset('dataset1')
+df_fruits = pd.DataFrame({'x': 6 * ['fruit'], 'y': list('🍓🥝🍇🍐🍏🍍')})
+fruits = dataset1.create_table_from(df_fruits, 'fruits')
+fruits.aspandas()
+
+dataset2 = project.create_dataset('dataset2')
+df_vegetables = pd.DataFrame({'x': 5 * ['vegetable'], 'y': list('🥑🌽🥒🍆🥦')})
+vegetables = dataset2.create_table_from(df_vegetables, 'vegetables')
+vegetables.aspandas()
+
+dataset3 = project.create_dataset('dataset3')
+query = """
+SELECT * FROM dataset1.fruits
+UNION
+SELECT * FROM dataset2.vegetables
+ORDER BY x, y
+"""
+food = dataset3.create_table_as(query, 'food')
+food.aspandas()
+```
 ## Creation of a table from an ESAP ESFRI query
 
 We can store the result of an ESAP-API query into a table that belongs to the dataset that we have just created.

esap_client/models/datasets.py

@@ -71,6 +71,22 @@ def create_table_from(
         raise_for_status(response)
         return Table.deserialize(response.json())
 
+    def create_table_as(
+        self, query: str, name: Optional[str] = None, description: str = ''
+    ) -> Table:
+        """Creates a table from a SQL query."""
+        if not isinstance(query, str):
+            raise TypeError('The query is not a string.')
+
+        payload = {
+            'name': name,
+            'description': description,
+            'query': query,
+        }
+        response = self.session.post('/tables', payload)
+        raise_for_status(response)
+        return Table.deserialize(response.json())
+
     def create_table_from_esap_gateway_query(
         self, query: dict, name: str, description: str = ''
     ) -> Table: