Load a JSON file from disk into memory.

Args: file_path: Absolute or relative path to the JSON file. alias: Optional friendly name for the document (defaults to filename stem). replace: Set true to reload an alias that is already loaded.

Returns: Summary of the loaded document including type, size, and item count.

List all currently loaded JSON documents with their metadata.

Returns: A formatted table showing alias, type, item count, size, and path for each loaded document, or a message if none are loaded.

Remove a loaded JSON document from memory.

Args: alias: The alias of the document to unload.

Returns: Confirmation that the document was unloaded.

Get all keys at a given path in a loaded JSON document.

Works on objects (returns key names) and arrays (returns index count).

Args: alias: The alias of the loaded document. path: Dot/bracket notation path to navigate into the document. Examples: "", "data.users", "items[0].tags". Empty string means root.

Returns: List of keys (for objects) or item count (for arrays).

Retrieve the value at an exact path in a loaded JSON document.

The output is automatically truncated if it exceeds 10KB to prevent overwhelming the context window.

Args: alias: The alias of the loaded document. path: Dot/bracket notation path. Empty string means root.

Returns: The JSON value at the given path (serialized, possibly truncated).

Return the JSON type of the value at a given path.

Possible types: object, array, string, number, boolean, null. For objects and arrays, also includes the count of keys/items.

Args: alias: The alias of the loaded document. path: Dot/bracket notation path. Empty string means root.

Returns: The JSON type (e.g. "object (5 keys)", "array (100 items)", "string").

Return a schema-like skeleton of a JSON document showing keys and types.

Useful for understanding the shape of deeply nested JSON without viewing all the actual data.

Args: alias: The alias of the loaded document. path: Dot/bracket notation path. Empty string means root. max_depth: How many levels deep to show (default 3).

Returns: An indented tree showing the document structure with types.

Execute a JSONPath expression against a loaded JSON document.

Use standard JSONPath syntax to extract data. Examples:

• $.users[*].email — all user emails

• $.orders[?@.total>100] — orders over 100

• $.config.database.host — specific nested value

Args: alias: The alias of the loaded document. expression: A JSONPath expression (must start with $).

Returns: The matched values as a list, or a message if nothing matched.

Filter an array of objects by a field condition.

Operators: eq, neq, gt, gte, lt, lte, contains, regex.

Args: alias: The alias of the loaded document. path: Dot-notation path to the array (e.g. "products", "data.users"). field: The field name to filter on (e.g. "status", "price"). operator: Comparison operator (eq, neq, gt, gte, lt, lte, contains, regex). value: The value to compare against.

Returns: The filtered objects with a match count header.

Recursively search all string values for a substring or regex pattern.

Returns the paths and values of every match found. Useful for finding where a specific term appears anywhere in a large JSON document. Walks as deep as Python allows unless max_depth is set.

Args: alias: The alias of the loaded document. pattern: A substring or regex pattern to search for. path: Optional starting path to narrow the search scope. case_sensitive: Whether matching is case-sensitive (default False). max_depth: Stop after this many nested levels. Omit to walk the full safe depth.

Returns: A list of matching paths and their string values.

Count items in an array or keys in an object at a given path.

Args: alias: The alias of the loaded document. path: Dot/bracket notation path. Empty string means root.

Returns: The item/key count at the given path.

Sum numeric values matched by a JSONPath expression.

Args: alias: The alias of the loaded document. expression: A JSONPath expression resolving to numbers (e.g. "$.orders[*].total").

Returns: The sum and count of matched numeric values.

Get the minimum and maximum of numeric values matched by a JSONPath expression.

Args: alias: The alias of the loaded document. expression: A JSONPath expression resolving to numbers.

Returns: The min, max, and count of matched values.

Get distinct values matched by a JSONPath expression.

Args: alias: The alias of the loaded document. expression: A JSONPath expression (e.g. "$.users[*].role").

Returns: A list of unique values with count information.

Count occurrences of each distinct value matched by a JSONPath expression.

Like a frequency table: shows each unique value and how many times it appears. Results are sorted by count (most common first).

Args: alias: The alias of the loaded document. expression: A JSONPath expression (e.g. "$.orders[*].status").

Returns: A frequency table with values and their counts.

Flatten a nested JSON object into dot-notation key-value pairs.

Converts nested structures like {"a": {"b": 1}} into {"a.b": 1}. Walks as deep as Python allows unless max_depth is set.

Args: alias: The alias of the loaded document. path: Dot-notation path to the object to flatten. Empty means root. separator: The separator for flattened keys (default "."). max_depth: Stop after this many nested levels. Omit to walk the full safe depth.

Returns: A flat mapping of dotted-path keys to their values.

Extract specific fields from each object in an array (projection).

Like SQL SELECT — picks only the columns you care about.

Args: alias: The alias of the loaded document. path: Dot-notation path to the array of objects. fields: List of field names to include (e.g. ["name", "price"]).

Returns: The projected array containing only the specified fields.

Group an array of objects by a field value.

Args: alias: The alias of the loaded document. path: Dot-notation path to the array of objects. field: The field to group by (e.g. "category", "status").

Returns: A summary of groups with counts, plus the grouped data.

Sort an array of objects by a field.

Args: alias: The alias of the loaded document. path: Dot-notation path to the array of objects. field: The field to sort by (e.g. "price", "name"). descending: Sort in descending order (default False = ascending).

Returns: The sorted array.

Return N random items from an array.

Useful for previewing large datasets without loading everything.

Args: alias: The alias of the loaded document. path: Dot-notation path to the array. Empty means root. n: Number of items to sample (default 5). seed: Optional random seed for reproducible results.

Returns: N randomly selected items from the array.

Get a full statistical summary of numeric values matched by a JSONPath.

Returns count, mean, median, standard deviation, min, max, 25th/75th percentiles, and sum — like pandas .describe() for JSON.

Args: alias: The alias of the loaded document. expression: A JSONPath expression resolving to numbers (e.g. "$.orders[*].total").

Returns: A formatted statistical summary table.

Filter an array of objects with multiple conditions combined by AND/OR.

Each condition is a dict with keys: field, operator, value. Operators: eq, neq, gt, gte, lt, lte, contains, regex.

Examples:

• [{"field": "status", "operator": "eq", "value": "active"}, {"field": "score", "operator": "gt", "value": 80}]

• mode="and" means ALL conditions must match.

• mode="or" means ANY condition can match.

Args: alias: The alias of the loaded document. path: Dot-notation path to the array of objects. conditions: List of condition dicts. mode: "and" or "or" (default "and").

Returns: The filtered objects with a match count header.

Compare two JSON values and report their differences.

Can compare two paths within the same document or across two documents. Reports added keys, removed keys, type changes, and value changes. Walks as deep as Python allows unless max_depth is set.

Args: alias_a: The alias of the first document. path_a: Path to the first value (default root). alias_b: The alias of the second document (defaults to alias_a). path_b: Path to the second value (default root). max_depth: Stop after this many nested levels. Omit to walk the full safe depth.

Returns: A structured diff report listing all differences found.

Export an array of objects to a CSV file.

If fields is omitted, all keys found across all objects are used as columns. Nested values (dicts, arrays) are serialized as JSON strings in the CSV.

Args: alias: The alias of the loaded document. path: Dot-notation path to the array of objects. output_path: File path for the output CSV. fields: Optional list of column names to include.

Returns: Confirmation with file path, row count, and column count.

Export a value at a path to a new JSON file.

Useful for saving a filtered subset or nested section of a large document.

Args: alias: The alias of the loaded document. output_path: File path for the output JSON. path: Dot-notation path to the value to export (default root). indent: JSON indentation level (default 2).

Returns: Confirmation with file path and size.

List every unique leaf path in a JSON document.

Essential for understanding the shape of an unknown JSON file. For arrays, only the first N items are sampled to discover paths efficiently without scanning thousands of identical objects.

Args: alias: The alias of the loaded document. path: Starting path (default root). max_depth: Maximum recursion depth (default 10). sample_array_items: How many array elements to inspect (default 5).

Returns: A list of all discovered paths with their JSON types.