adds sql query method for stream metadata [ch251]

Author: looselycoupled

btrdb/conn.py

@@ -17,6 +17,7 @@
 
 import os
 import re
+import json
 import uuid as uuidlib
 
 import grpc
@@ -102,6 +103,43 @@ class BTrDB(object):
     def __init__(self, endpoint):
         self.ep = endpoint
 
+    def query(self, stmt, params=[]):
+        """
+        Performs a SQL query on the database metadata and returns a list of
+        dictionaries from the resulting cursor.
+
+        Parameters
+        ----------
+        stmt: str
+            a SQL statement to be executed on the BTrDB metadata.  Available
+            tables are noted below.  To sanitize inputs use a `$1` style parameter such as
+            `select * from streams where name = $1 or name = $2`.
+        params: list or tuple
+            a list of parameter values to be sanitized and interpolated into the
+            SQL statement. Using parameters forces value/type checking and is
+            considered a best practice at the very least.
+
+        Returns
+        -------
+        list
+            a list of dictionary object representing the cursor results.
+
+
+        Notes
+        -------
+        Parameters will be inserted into the SQL statement as noted by the
+        paramter number such as `$1`, `$2`, or `$3`.  The `streams` table is
+        available for `SELECT` statements only.
+
+        See https://btrdb.readthedocs.io/en/latest/ for more info.
+        """
+        return [
+            json.loads(row.decode("utf-8"))
+            for page in self.ep.sql_query(stmt, params)
+            for row in page
+        ]
+
+
     def streams(self, *identifiers, versions=None):
         """
         Returns a StreamSet object with BTrDB streams from the supplied

btrdb/endpoint.py

@@ -212,3 +212,9 @@ def generateCSV(self, queryType, start, end, width, depth, includeVersions, *str
         for result in self.stub.GenerateCSV(params):
             BTrDBError.checkProtoStat(result.stat)
             yield result.row
+
+    def sql_query(self, stmt, params=[]):
+        request = btrdb_pb2.SQLQueryParams(query=stmt, params=params)
+        for page in self.stub.SQLQuery(request):
+            BTrDBError.checkProtoStat(page.stat)
+            yield page.SQLQueryRow

docs/source/working/stream-query-manage.rst

@@ -44,7 +44,7 @@ supplied UUID cannot be found then :code:`None` will be returned.
     stream = conn.stream_from_uuid("71466a91-dcfe-42ea-9e88-87c51f847942")
 
 
-Query by collection
+Finding by collection
 --------------------------
 You can also search for multiple streams by collection using the server object's
 :code:`streams_in_collection` method which will return a simple list of
@@ -56,3 +56,44 @@ detail.
 
     conn = btrdb.connect()
     streams = conn.streams_in_collection("NORTHEAST/NH")
+
+
+Querying Metadata
+-----------------
+Finally, you can query for metadata using standard SQL although at the moment, only the
+`streams` table is available.  SQL queries can be submitted using the `query`
+method which accepts both a `stmt` and `params` argument.  The `stmt` should
+contain the SQL you'd like executed with parameter placeholders such as `$1` or
+`$2` as shown below.
+
+.. code-block:: python
+
+    conn = btrdb.connect()
+    stmt = "select uuid from streams where name = $1 or name = $2"
+    params = ["Boston_1", "Boston_2"]
+
+    for row in conn.query(stmt, params):
+      print(row)
+
+The SQL query results are returned as a list of dictionaries where each key
+matches a column from your SQL projection.  You can choose your columns from the
+schema of the streams table as follows.
+
+
++------------------+------------------------+-----------+
+|      Column      |          Type          | Nullable  |
++==================+========================+===========+
+| uuid             | uuid                   | not null  |
++------------------+------------------------+-----------+
+| collection       | character varying(256) | not null  |
++------------------+------------------------+-----------+
+| name             | character varying(256) | not null  |
++------------------+------------------------+-----------+
+| unit             | character varying(256) | not null  |
++------------------+------------------------+-----------+
+| ingress          | character varying(256) | not null  |
++------------------+------------------------+-----------+
+| property_version | bigint                 | not null  |
++------------------+------------------------+-----------+
+| annotations      | hstore                 |           |
++------------------+------------------------+-----------+