docs: Add ticking data example with timer-based flushing. (#7)

Author: marregui

docs/examples.rst

@@ -46,3 +46,14 @@ all data is sent.
 .. literalinclude:: ../examples/buffer.py
    :language: python
 
+
+Ticking Random Data and Timer-based Flush
+=========================================
+
+The following example somewhat mimics the behavior of a loop in an application.
+
+It creates random ticking data at a random interval and flushes it explicitly
+based on a timer if the auto-flushing logic was not triggered recently.
+
+.. literalinclude:: ../examples/random_data.py
+   :language: python

examples/auth_and_tls.py

@@ -1,14 +1,14 @@
 from questdb.ingress import Sender
 
 
-def example():
+def example(host: str = 'localhost', port: int = 9009):
     # See: https://questdb.io/docs/reference/api/ilp/authenticate
     auth = (
         "testUser1",                                    # kid
         "5UjEMuA0Pj5pjK8a-fa24dyIf-Es5mYny3oE_Wmus48",  # d
         "fLKYEaoEb9lrn3nkwLDA-M_xnuFOdSt9y0Z7_vWSHLU",  # x
         "Dt5tbS1dEDMSYfym3fgMv0B99szno-dFc1rYF9t0aac")  # y
-    with Sender('localhost', 9009, auth=auth, tls=True) as sender:
+    with Sender(host, port, auth=auth, tls=True) as sender:
         sender.row(
             'line_sender_example',
             symbols={'id': 'OMEGA'},
@@ -21,4 +21,4 @@ def example():
 
 
 if __name__ == '__main__':
-    example()
+    example()

examples/basic.py

@@ -1,8 +1,8 @@
 from questdb.ingress import Sender
 
 
-def example():
-    with Sender('localhost', 9009) as sender:
+def example(host: str = 'localhost', port: int = 9009):
+    with Sender(host, port) as sender:
         sender.row(
             'line_sender_example',
             symbols={'id': 'OMEGA'},
@@ -15,4 +15,4 @@ def example():
 
 
 if __name__ == '__main__':
-    example()
+    example()

examples/buffer.py

@@ -1,8 +1,8 @@
 from questdb.ingress import Sender, TimestampNanos
 
 
-def example():
-    with Sender('localhost', 9009) as sender:
+def example(host: str = 'localhost', port: int = 9009):
+    with Sender(host, port) as sender:
         buffer = sender.new_buffer()
         buffer.row(
             'line_sender_buffer_example',
@@ -18,4 +18,4 @@ def example():
 
 
 if __name__ == '__main__':
-    example()
+    example()

examples/random_data.py

@@ -0,0 +1,47 @@
+from questdb.ingress import Sender
+import random
+import uuid
+import time
+
+
+def example(host: str = 'localhost', port: int = 9009):
+    table_name: str = str(uuid.uuid1())
+    watermark = 1024  # Flush if the internal buffer exceeds 1KiB
+    with Sender(host=host, port=port, auto_flush=watermark) as sender:
+        total_rows = 0
+        last_flush = time.monotonic()
+        try:
+            print("Ctrl^C to terminate...")
+            while True:
+                time.sleep(random.randint(0, 750) / 1000)  # sleep up to 750 ms
+
+                print('Inserting row...')
+                sender.row(
+                    table_name,
+                    symbols={
+                        'src': random.choice(('ALPHA', 'BETA', 'OMEGA')),
+                        'dst': random.choice(('ALPHA', 'BETA', 'OMEGA'))},
+                    columns={
+                        'price': random.randint(200, 500),
+                        'qty': random.randint(1, 5)})
+                total_rows += 1
+
+                # If the internal buffer is empty, then auto-flush triggered.
+                if len(sender) == 0:
+                    print('Auto-flush triggered.')
+                    last_flush = time.monotonic()
+
+                # Flush at least once every five seconds.
+                if time.monotonic() - last_flush > 5:
+                    print('Timer-flushing triggered.')
+                    sender.flush()
+                    last_flush = time.monotonic()
+
+        except KeyboardInterrupt:
+            print(f"table: {table_name}, total rows sent: {total_rows}")
+            print("(wait commitLag for all rows to be available)")
+            print("bye!")
+
+
+if __name__ == '__main__':
+    example()