Kusto Plugin#

class graphistry.plugins.kusto.KustoMixin(*args, **kwargs)#

Bases: Plottable

KustoMixin is a Graphistry Mixin that allows you to plot data from Kusto.

configure_kusto(cluster, database='NetDefaultDB', client_id=None, client_secret=None, tenant_id=None)#

Configure Azure Data Explorer (Kusto) connection settings.

Sets up the connection parameters for accessing a Kusto cluster. Authentication can be done via service principal (client_id, client_secret, tenant_id) or managed identity (omit authentication parameters).

Parameters:

cluster (str) – Kusto cluster URL (e.g., ‘https://mycluster.westus2.kusto.windows.net’)
database (str) – Database name (defaults to ‘NetDefaultDB’)
client_id (Optional[str]) – Azure AD application (client) ID for service principal auth
client_secret (Optional[str]) – Azure AD application secret for service principal auth
tenant_id (Optional[str]) – Azure AD tenant ID for service principal auth

Returns:

Self for method chaining

Return type:

Plottable

Example: Service principal authentication

import graphistry
g = graphistry.configure_kusto(
    cluster="https://mycluster.westus2.kusto.windows.net",
    database="SecurityDatabase",
    client_id="your-client-id",
    client_secret="your-client-secret",
    tenant_id="your-tenant-id"
)

Example: Managed identity authentication

import graphistry
g = graphistry.configure_kusto(
    cluster="https://mycluster.westus2.kusto.windows.net",
    database="SecurityDatabase"
    # No auth params - uses managed identity
)

kql(query: str, *, unwrap_nested: bool | None = None, single_table: Literal[True] = True) → List[DataFrame]#

kql(query: str, *, unwrap_nested: bool | None = None, single_table: Literal[False]) → DataFrame

kql(query: str, *, unwrap_nested: bool | None = None, single_table: bool = True) → DataFrame | List[DataFrame]

Execute KQL query and return result tables as DataFrames.

Submits a Kusto Query Language (KQL) query to Azure Data Explorer and returns the results. By default, expects a single table result and returns it as a DataFrame. If multiple tables are returned, only the first is returned with a warning. Set single_table=False to always get a list of all result tables.

Parameters:

query (str) – KQL query string to execute
unwrap_nested (Optional[bool]) – Strategy for handling nested/dynamic columns
single_table (bool) – If True, return single DataFrame (first table if multiple); if False, return list

Returns:

Single DataFrame if single_table=True, else list of DataFrames

Return type:

Union[pd.DataFrame, List[pd.DataFrame]]

unwrap_nested semantics:

True: Always attempt to unwrap nested columns; raise on failure
None: Use heuristic - unwrap if the first result looks nested
False: Never attempt to unwrap nested columns

Example: Basic security query (single table mode)

import graphistry
g = graphistry.configure_kusto(...)

query = '''
SecurityEvent
| where TimeGenerated > ago(1d)
| where EventID == 4624  // Successful logon
| project TimeGenerated, Account, Computer, IpAddress
| take 1000
'''

# Single table mode returns DataFrame directly (default)
df = g.kql(query)
print(f"Found {len(df)} logon events")

Example: Get all tables as list

# Always get a list of all tables
dfs = g.kql(query, single_table=False)
df = dfs[0]

Example: Multi-table query

query = '''
SecurityEvent | take 10;
Heartbeat | take 5
'''

# With single_table=True (default), returns first table with warning
df = g.kql(query)  # Returns SecurityEvent data, warns about multiple tables

# With single_table=False, returns all tables
frames = g.kql(query, single_table=False)
security_df = frames[0]
heartbeat_df = frames[1]

property kusto_client: Any#

kusto_close()#

Close the active Kusto client connection.

Properly closes the underlying Kusto client connection to free resources. This should be called when you’re done using the Kusto connection.

Example

import graphistry
g = graphistry.configure_kusto(...)
# ... perform queries ...
g.kusto_close()  # Clean up connection

Return type:: None

kusto_from_client(client, database='NetDefaultDB')#

Configure Kusto using an existing client connection.

Use this method when you already have a configured Kusto client connection and want to reuse it with Graphistry.

Parameters:

client (azure.kusto.data.KustoClient) – Pre-configured Kusto client
database (str) – Database name to query against

Returns:

Self for method chaining

Return type:

Plottable

Example

from azure.kusto.data import KustoClient, KustoConnectionStringBuilder
import graphistry

# Create Kusto client
kcsb = KustoConnectionStringBuilder.with_aad_device_authentication(
    "https://mycluster.kusto.windows.net"
)
kusto_client = KustoClient(kcsb)

# Use with Graphistry
g = graphistry.kusto_from_client(kusto_client, "MyDatabase")

kusto_graph(graph_name, snap_name=None)#

Fetch a Kusto graph entity as a Graphistry visualization object.

Retrieves a named graph entity (and optional snapshot) from Kusto using the graph() operator and graph-to-table transformation. The result is automatically bound as nodes and edges for visualization.

Parameters:

graph_name (str) – Name of the Kusto graph entity to fetch
snap_name (Optional[str]) – Optional snapshot/version identifier

Returns:

Plottable object ready for visualization or further transforms

Return type:

Plottable

Example: Basic graph visualization

import graphistry
g = graphistry.configure_kusto(...)

# Fetch and visualize a named graph
graph_viz = g.kusto_graph("NetworkTopology")
graph_viz.plot()

Example: Specific snapshot

# Fetch a specific snapshot of the graph
graph_viz = g.kusto_graph("NetworkTopology", "2023-12-01")
graph_viz.plot()

kusto_health_check()#

Perform a health check on the Kusto connection.

Executes a simple query (.show tables) to verify that the connection to the Kusto cluster is working properly.

Raises:: RuntimeError – If the connection test fails
Return type:: None

Example

import graphistry
g = graphistry.configure_kusto(...)
g.kusto_health_check()  # Verify connection works

graphistry.plugins.kusto.init_kusto_client(cfg)#

Parameters:: cfg (KustoConfig)
Return type:: Any

Kusto Plugin

Contents

Kusto Plugin#