Wherobots

execute_query_tool

Run the SQL query on a Wherobots catalog. ⚠️ WORKFLOW: ALWAYS test queries with this tool before generating code. Use limit=10 or limit=100 for initial testing to validate query logic. 📋 PREREQUISITES (required for reliable results): - search_documentation_tool: Understand correct SQL syntax - describe_table_tool: Verify table schema and column names - generate_spatial_query_tool: Generate the SQL (recommended) 📋 NEXT STEPS after this tool: - If query SUCCEEDS: Increase limit or remove it for full results - If query FAILS: Use sql_debug_workflow prompt, check schema, retry - Only generate application code AFTER SQL is validated and working This tool allows users to execute SQL queries against the Wherobots catalog. It is typically used for data retrieval and analysis. Supports pagination for large result sets. *** Remember: - Ensure the output can be serialized to JSON. - If query execution fails, analyze the error and provide a meaningful message to the user. - Use limit and offset parameters for large result sets to avoid timeouts. - Queries have a maximum execution time (configurable via settings or x-query-timeout header). - The runtime ID can be customized via the x-runtime-id header (default: tiny). - The runtime region can be customized via the x-runtime-region header (default: aws-us-west-2). - The server sends periodic heartbeat messages during long-running queries to keep the connection alive. - If the client disconnects, the query will be cancelled to avoid wasting resources. *** Parameters ---------- query : str The SQL query to be executed. ctx : Context FastMCP context (injected automatically) limit : int | None Optional maximum number of rows to return (default: 1000, max: 10000) offset : int | None Optional number of rows to skip for pagination (default: 0) Returns ------- QueryExecutionOutput A structured object containing the results of the query execution. - 'success': Whether the query executed successfully - 'row_count': Number of rows returned - 'data': Query results as a list of dictionaries - 'query': The executed SQL query - 'error': Whether an error occurred - 'error_type': Type of error (if any) - 'error_message': Error message (if any) - 'execution_status': Status of execution Example Usage for LLM: - When user asks to run a specific SQL query. - Example User Queries and corresponding Tool Calls: - User: "Run the following SQL query: SELECT * FROM buildings WHERE state = 'California';" - Tool Call: execute_query('SELECT * FROM buildings WHERE state = 'California';') - User: "Execute this query with only the first 100 results" - Tool Call: execute_query('SELECT * FROM large_table;', limit=100) - User: "Get the next page of results" - Tool Call: execute_query('SELECT * FROM large_table;', limit=100, offset=100)

search_documentation_tool

Search the Wherobots documentation. ⚠️ WORKFLOW: This should be your FIRST tool call for any query task. Before writing queries, ALWAYS search documentation to understand: - Available spatial functions and their syntax - Best practices and common patterns - Example queries for similar use cases 📋 NEXT STEPS after this tool: 1. Use catalog tools (list_catalogs, list_databases, list_tables) to find data 2. Use describe_table_tool to understand table schemas 3. Use generate_spatial_query_tool to create SQL queries This tool searches the official Wherobots documentation to find relevant information about spatial functions, data formats, best practices, and more. It's useful when users need help understanding Wherobots features or syntax. Parameters ---------- query : str The search query string ctx : Context FastMCP context (injected automatically) page_size : int | None Optional number of results to return (default: 10) Returns ------- DocumentationSearchOutput A structured object containing documentation search results. - 'results': List of DocumentResult objects, each containing: - 'content': The documentation content snippet - 'path': The URL path to the documentation page - 'metadata': Additional metadata about the result Example Usage for LLM: - When user asks about Wherobots features, functions, or syntax - When generating queries and need context about spatial functions - Example User Queries and corresponding Tool Calls: - User: "How do I use ST_INTERSECTS in Wherobots?" - Tool Call: search_documentation("ST_INTERSECTS spatial function") - User: "What spatial functions are available for distance calculations?" - Tool Call: search_documentation("spatial distance functions") - User: "How do I connect to Wherobots from Python?" - Tool Call: search_documentation("Python connection API") For the best way to understand how to use spatial SQL in Wherobots, refer to the following Wherobots Documentation: - Writing Effective Spatial Queries in Wherobots: https://docs.wherobots.com/develop/write-spatial-queries - Writing Effective Spatial Queries in Wherobots complete example sub-section: https://docs.wherobots.com/develop/write-spatial-queries#complete-example:-counting-baseball-stadiums-in-the-us The complete example demonstrates: - Starting the `SedonaContext` - Using `wkls` where applicable - Loading spatial data from Wherobots tables - Using the correct schema from wherobots_open_data spatial catalogs - Writing spatial SQL queries effectively