histogram
Analyze and visualize data distributions by generating histograms from SQL queries on CSV or Parquet sources using DuckDB syntax. Ideal for exploring columnar data patterns with optional color grouping and bin customization.
Instructions
Run query against specified source and make a histogram using result For both csv and parquet sources, use DuckDB SQL syntax Use 'CSV' as the table name in the SQL query for csv sources. Use 'PARQUET' as the table name in the SQL query for parquet sources.
This will return an image of the plot
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| color | No | Optional; column name from SQL result to use for drawing multiple colored histograms representing another dimension | |
| column | Yes | Column name from SQL result to use for the histogram | |
| nbins | No | Optional; number of bins | |
| query | Yes | SQL query to run on the data source | |
| source_id | Yes | The data source to run the query on |
Implementation Reference
- zaturn/tools/visualizations.py:123-157 (handler)The handler function for the 'histogram' MCP tool. Runs SQL query on data source, creates histogram with plotly.express, converts to PNG image, returns ImageContent or error string.def histogram(self, source_id: Annotated[ str, Field(description='The data source to run the query on') ], query: Annotated[ str, Field(description='SQL query to run on the data source') ], column: Annotated[ str, Field(description='Column name from SQL result to use for the histogram') ], color: Annotated[ str | None, Field(description='Optional; column name from SQL result to use for drawing multiple colored histograms representing another dimension') ] = None, nbins: Annotated[ int | None, Field(description='Optional; number of bins') ] = None, ) -> str | ImageContent: """ Run query against specified source and make a histogram using result For both csv and parquet sources, use DuckDB SQL syntax Use 'CSV' as the table name in the SQL query for csv sources. Use 'PARQUET' as the table name in the SQL query for parquet sources. This will return an image of the plot """ try: df = self._get_df_from_source(source_id, query) fig = px.histogram(df, x=column, color=color, nbins=nbins) fig.update_xaxes(autotickangles=[0, 45, 60, 90]) return _fig_to_image(fig) except Exception as e: return str(e)
- zaturn/tools/visualizations.py:27-40 (registration)Initializes Visualizations class and registers 'histogram' method in self.tools list for later exposure as MCP tools.def __init__(self, data_sources): self.data_sources = data_sources self.tools = [ self.scatter_plot, self.line_plot, self.histogram, self.strip_plot, self.box_plot, self.bar_plot, self.density_heatmap, self.polar_scatter, self.polar_line, ]
- zaturn/tools/__init__.py:6-10 (registration)ZaturnTools aggregates tools from Core and Visualizations (including histogram), exposing them via self.tools.def __init__(self, data_sources): self.tools = [ *core.Core(data_sources).tools, *visualizations.Visualizations(data_sources).tools, ]
- zaturn/mcp/__init__.py:90-94 (registration)Registers all tools from ZaturnTools (including histogram) to the FastMCP server instance.zaturn_tools = ZaturnTools(sources) zaturn_mcp = FastMCP() for tool_function in zaturn_tools.tools: zaturn_mcp.add_tool(Tool.from_function(tool_function))
- zaturn/tools/visualizations.py:13-23 (helper)Helper function to convert Plotly figure to base64-encoded ImageContent, used by histogram and other visualization tools.def _fig_to_image(fig): fig_encoded = b64encode(fig.to_image(format='png')).decode() img_b64 = "data:image/png;base64," + fig_encoded return ImageContent( type = 'image', data = fig_encoded, mimeType = 'image/png', annotations = None, )