This section outlines how SuzieQ Query Engine organizes and executes queries, with clear examples to help you get started:

1. Understand the Query Format:
   • All queries use the structure: <table> <verb> [filters].
   • Table: Indicates the dataset you want to analyze (like bgp, interface, or route).
   • Verb: Defines the operation, such as show (view entries), summarize (summary stats), or unique (distinct values).
   • Filters: Optional conditions to narrow the output (like state=up, hostname=spine01, or mtu=">1500").
2. Basic Query Example:
   • Display all BGP sessions: bgp show
   • List interfaces on a specific device: interface show hostname=spine01
3. Using Filters for Precision:
   • Find only non-established BGP sessions: bgp show state=NotEstd
   • Show interfaces that are down: interface show state=down
4. Leverage Advanced Expressions:
   • Advanced conditions support Pandas-like expressions using AND, OR, and parentheses.
   • Example: interfaces with MTU between 1,500 and 9,000:
     interface show mtu=">1500 <9000"
5. Select Output Columns and Format:
   • Add columns=<field1,field2> to display specific fields.
   • Specify return type (format=json, format=csv, etc.) for automation or reporting.
   • Example: route show columns=prefix,nhintf format=csv

SuzieQ organizes network information into logical tables. Each table represents a critical aspect of network state, making queries intuitive and efficient. Here’s an overview of the most common tables you’ll use:

• bgp:
  Contains BGP neighbor details, including session status and peer information. Useful for analyzing routing adjacency and connection health.
• ospf:
  Holds OSPF adjacency and neighbor state data for devices running OSPF. Ideal for troubleshooting dynamic routing environments.
• route:
  Tracks routing table entries, next-hop resolution, and route selection. Crucial for path and reachability checks.
• interface:
  Shows device interface information such as operational status, speed, duplex, MTU, and assigned VLANs.
• device:
  Lists inventory and metadata, covering device types, roles, operating system versions, and platform details.
• arp:
  Contains ARP table entries for mapping IPs to MAC addresses. Useful for troubleshooting L2/L3 issues.
• lldp:
  Shows LLDP neighbor data, supporting discovery of physical connections and verifying cabling.
• mac:
  Provides MAC forwarding table details. Helps in locating endpoints and analyzing L2 forwarding.

To see a full list of available tables in your SuzieQ deployment, you can run:
table show

Choosing the right table is the first step in crafting a focused and effective network query.

Filters and query expressions in SuzieQ empower you to zero in on the network data that matters most. This section walks you through building both simple and advanced filters, step by step.

1. Basic Filtering:
   • Focus on a specific device: hostname="leaf01"
   • Match several devices by listing them: hostname="leaf01" or hostname="spine01"
   • Or more efficiently, in a list: hostname=["leaf01", "spine01"]
2. Advanced Filtering:
   • Combine conditions using and, or, and parentheses.
     Example: hostname="spine01" and state="up"
   • Exclude items with !=:
     hostname != "leaf01"
   • Filter numerical values:
     mtu > 1500 or 1500 < mtu < 9000
3. Regular Expressions:
   • Use .str.contains() for pattern matching.
     Example: all hostnames starting with “spine”: hostname.str.contains("spine")
   • Match interface names using patterns:
     ifname.str.contains("1/[1-9]$")
4. Time and View Filters:
   • Specify a time range for queries:
     start-time="-1d" (last day), end-time="2025-07-23"
   • Control data type shown with view:
     view=latest (default) or view=changes
5. Query Expression Syntax:
   • String equality requires double quotes: hostname == "leaf01"
   • Regular expressions and lists enhance matching power
   • Example combining several techniques:
     (hostname=="spine01" or hostname=="spine02") and mtu > 1500

Use the query_str parameter for complex expressions and experiment with combining different filters for more targeted results.

SuzieQ Query Engine supports several output formats, allowing you to easily integrate its results into different workflows and automation pipelines. Here’s how to select and use each format:

1. Plain Text:
   • The default output when running commands interactively or via CLI.
   • Human-readable, ideal for troubleshooting directly in a terminal session.
   • Example: interface show
2. JSON:
   • Returns structured output for programmatic processing.
   • Well-suited for integration with scripts, APIs, and automation tools.
   • Example: route show format=json
3. CSV:
   • Tabular data export compatible with spreadsheets, reporting software, or custom analytics.
   • Easily imported into tools like Excel.
   • Example: bgp show format=csv
4. Markdown:
   • Output is formatted for documentation, wikis, or blog articles.
   • Useful for sharing results in collaborative environments.
   • Example: device show format=markdown

Choose the format that best fits your use case by adding the format parameter to your query. Adjusting the output makes it simpler to automate reporting, share findings, or feed results into downstream tools in your network operations workflow.

SuzieQ is built for integration and automation, enabling network teams to streamline operations, enhance visibility, and embed observability into workflows. Here’s how you can automate SuzieQ and connect it with your existing toolchain:

1. REST API Integration:
   • SuzieQ ships with a REST API that exposes the complete suite of query and data retrieval capabilities.
   • Automate common tasks—such as fetching interface states or validating BGP sessions—by calling REST endpoints from scripts, orchestration frameworks, or monitoring systems.
   • The REST server includes an interactive Swagger UI interface (usually at /api/docs), making it easy to test queries and generate client code.
   • Sample API usage to retrieve network device inventory:
     GET /api/v1/device/
2. Python Module:
   • SuzieQ can be imported as a Python library, letting you interact with network data as Pandas DataFrames.
   • Use Python scripts or Jupyter notebooks for custom analysis, scheduled validation, or network documentation generation.
   • Example usage:
     from suzieq.sqobjects import get_sqobject
bgp = get_sqobject('bgp')
bgp_tbl = bgp.fetch(hostname="spine01")
3. GUI Integration:
   • The Web UI offers intuitive visualization, assisted query-building, and easy export for sharing observability data.
   • Useful for teams who want a no-code experience, while advanced users can build and test queries before automating them.
4. Connecting with Third-Party Tools:
   • Integrate SuzieQ with inventory platforms such as NetBox for enriched state validation and automated documentation.
   • Results from queries can be routed to ticketing, alerting, or change management systems to trigger automated remediation or notifications.
5. Workflow Suggestions:
   • Schedule periodic checks—like auditing configurations or validating compliance—using Python scripts or REST endpoints in cron jobs.
   • Incorporate SuzieQ queries into CI/CD pipelines to validate infrastructure changes before and after deployments.
   • Use webhooks or REST calls to push critical network changes or findings into chatops channels or dashboards.

Whether you prefer scripting, point-and-click, or integrating directly with other automation tools, SuzieQ flexibly adapts to your organization’s observability and network automation workflows.

Applying best practices ensures your SuzieQ experience is efficient, consistent, and delivers reliable network insights. Here’s a step-by-step approach for making the most of SuzieQ Query Engine:

1. Organize by Namespace:
   • Use namespaces to logically segment network infrastructure—by location, function, or business unit. This keeps queries focused and makes large environments manageable.
   • Example: interface show namespace=prod-campus
2. Leverage Filters Early:
   • Always use filters (like hostname, state, or mtu) to narrow your result sets. This speeds up analysis and reduces noise.
   • Example: route show namespace=prod state=active
3. Use Time Windows for Change Tracking:
   • Add start-time and end-time to investigate network changes, troubleshooting, or audits.
   • Example: bgp show start-time="-2h"
4. Summarize and Get Unique Values:
   • Use summarize to get high-level statistics, which are ideal for dashboards and health checks.
   • Example: interface summarize namespace=core
   • Use unique to quickly inventory VLANs, next hops, or device types.
   • Example: interface unique vlan
5. Automate Checks and Reporting:
   • Schedule routine checks using the REST API or Python module to validate states or compliance.
   • Output queries in JSON or CSV for integration with ticketing or reporting systems.
   • Example: device show format=json
6. Track and Document Incidents:
   • Export query results in Markdown to share in documentation, wikis, or team chat for faster incident response.
   • Example: bgp show format=markdown
7. Validate and Standardize Inventory:
   • Regularly run inventory queries and validate devices for configuration drift or unexpected changes.
   • Example: device show

Following these practices will help you achieve faster problem resolution, clearer analytics, and a more reliable, well-documented network environment.

Being able to quickly pinpoint network issues is essential. SuzieQ comes with a set of practical queries for common troubleshooting scenarios. This section guides you through typical tasks and the queries to accomplish them:

You can modify these queries to fit more targeted investigations by applying filters or changing the time range. Having a standard troubleshooting toolkit accelerates both simple checks and deep dives.

SuzieQ continues to evolve with each release, introducing new features, improvements, and expanded integrations. Stay abreast of the latest updates to take full advantage of recent enhancements. Here’s a step-by-step outline of common change types to watch for:

1. REST API Improvements:
   • Performance enhancements in REST endpoints for faster data retrieval.
   • Additional endpoints to cover new query types and network state data.
   • More comprehensive error messages and improved documentation at /api/docs.
2. Enhanced Filtering Support:
   • Support for advanced range queries on numeric fields, improving precision when troubleshooting metrics like MTU or status codes.
   • Ability to filter with multiple conditions, regular expressions, and lists.
3. NetBox Integration:
   • Multi-tag support in NetBox queries, allowing richer device and inventory selection from automation scripts and UI.
4. Assertion Reason Columns:
   • Added columns to assertion outputs to explain the reasoning behind pass/fail states, speeding up root cause analysis.
5. Additional Enhancements:
   • UI and CLI refinements for more intuitive workflows.
   • Expanded device, interface, or protocol support in logical tables.
   • Streamlined export and reporting options for all output formats.

Check release notes regularly to stay updated on new commands, filters, performance tweaks, and integration capabilities in your version of SuzieQ.