Streamlit integration

This page documents the API for using the Streamlit library with PyKX.

`PyKXConnection`

Bases: BaseConnection[SyncQConnection]

A connection to a q server from Streamlit. Initialise using:

st.connection("<name>", type = pykx.streamlit.PyKXConnection, *args)

Warning

Streamlit integration is not supported for Windows. Full utilization requires PYKX_THREADING which is not supported on windows.

Parameters:

Name	Description	Default
`host`	Server host name.	required
`port`	Server port number.	required
`username`	Username for q connection.	required
`password`	Password for q connection.	required
`timeout`	The number of seconds before a blocking operation times out. A value of 0 creates a non-blocking connection.	required
`large_messages`	Boolean flag to enable/disable support for messages >2GB.	required
`tls`	Boolean flag to enable/disable TLS.	required
`unix`	Boolean flag to enable Unix domain socket connection. Host parameter is ignored if `True`. Does not work on Windows.	required
`wait`	Boolean to enable/disable waiting for the q server to complete executing the query and return the result. `False` emulates async queries, causing the q server to respond immediately with the generic null `::` and perform calculations at another time.	required
`reconnection_attempts`	The number of maximum attempts to reconnect when a connection is lost. A negative number prevents any attempts to reconnect. A value of 0 will cause continuous reconnect attempts until a connection is established. Positive values are the number of times to attempt. Successive reconnect attempts are run at exponentially increasing backoff times. Hitting the maximum number of limits with unsuccessful attempts will throw an error.	required

The username and password parameters are not required.

The username and password parameters are only required if the q server requires authorization. Refer to ssl documentation for more information.

The timeout argument may not always be enforced when making succesive querys.

When making successive queries if one query times out the next query will wait until a response has been recieved from the previous query before starting the timer for its own timeout. This can be avioded by using a seperate SyncQConnection instance for each query.

Examples:

Open a streamlit connection to a locally running q process on port 5050.

>>> import streamlit as st
>>> import pykx as kx
>>> conn = st.connection('pykx', type=kx.streamlit.PyKXConnection,
...                      host = 'localhost', port = 5050)
>>>

reset

reset(**kwargs)

Close and reopen an existing Streamlit connection.

Example:

Open a connection to a locally running process on port 5050 and check if it is a healthy connection. If it is not, reset the connection.

>>> import streamlit as st
>>> import pykx as kx
>>> conn = st.connection('pykx', type=kx.streamlit.PyKXConnection,
...                      host = 'localhost', port = 5050)
>>> if not conn.is_healthy():
...     conn.reset()
>>>

is_healthy

is_healthy()

Check if an existing streamlit connection is 'healthy' and available for query.

Returns:

Type	Description
`bool`	A boolean indicating if the connection being used is in a 'healthy' state

>>> import streamlit as st
>>> import pykx as kx
>>> conn = st.connection('pykx', type=kx.streamlit.PyKXConnection,
...                      host = 'localhost', port = 5050)
>>> conn.is_healthy()
True

query

query(query, *args, format='q', **kwargs)

Query the connected q process over IPC.

Parameters:

Name	Type	Description	Default
`query`	`str`	A q expression to be evaluated. This must be valid q, qSQL or SQL in the KX Insights style.	required
`*args`		Arguments to the query. Each argument will be converted into a `pykx.K` object. Up to 8 arguments can be provided (maximum supported by q functions).	`()`
`format`		Description of query format for internal pre-processing before the query is sent to the server. This must be one of 'q', 'qsql' or 'sql'.	`'q'`

Raises:

Type	Description
`RuntimeError`	A closed IPC connection was used.
`QError`	Query timed out, may be raised if the time taken to make or receive a query goes over the timeout limit.
`TypeError`	Too many arguments were provided - q queries cannot have more than 8 parameters.
`ValueError`	Attempted to send a Python function over IPC.

Examples:

Open a connection to a locally running q process on port 5050 and query using 'q' format.

>>> import streamlit as st
>>> import pykx as kx
>>> conn = st.connection('pykx', type=kx.streamlit.PyKXConnection,
...                      host = 'localhost', port = 5050)
>>> df = conn.query('select from tab').pd()
>>> st.dataframe(df)

Open a connection to a locally running q process on port 5050 and query using 'qsql' format.

>>> import streamlit as st
>>> import pykx as kx
>>> conn = st.connection('pykx', type=kx.streamlit.PyKXConnection,
...                      host = 'localhost', port = 5050)
>>> df = conn.query('tab', where='x>0.5', format='qsql').pd()
>>> st.dataframe(df)

Connect to a locally running q process on port 5050 and query using 'sql' format.

>>> import streamlit as st
>>> import pykx as kx
>>> conn = st.connection('pykx', type=kx.streamlit.PyKXConnection,
...                      host = 'localhost', port = 5050)
>>> df = conn.query('select * from tab where x>0.5', format='sql').pd()
>>> st.dataframe(df)