{"openapi":"3.1.0","info":{"title":"Database MCP Server","description":"Read-only SQL over two engines: Postgres (men's and women's T20, ODI and Test internationals, plus the IPL) and DuckDB (men's and women's T20, ODI and Test internationals, plus the IPL). Both carry the same ball-by-ball tables, so the engine is a choice of SQL dialect, not of format. Each also has a match_info companion joined on match_id. Exposed as MCP tools for AI client consumption.\n\n## Download the whole dataset\n\nEvery table is published as parquet and CSV, and all files together as a DuckDB or SQLite database. Free, no signup, no key. Details in \"Want the whole table?\" below.\n\n- On this service: `/downloads` (redirects to the files)\n- Direct: `api.tigzig.com/cricket/v1/download`\n- From a browser: [www.tigzig.com/apis/database](https://www.tigzig.com/apis/database)\n\n## Restricted use\n\nThis is a read-only service. It runs SELECT, SHOW, DESCRIBE, EXPLAIN and WITH against the cricket tables above, using a published set of functions. Anything outside that is refused.\n\nPlease stay inside it. These are not available:\n\n- Writing or changing anything. Inserts, updates, deletes, creating or dropping tables, SELECT INTO.\n- Reading files or web addresses. This includes our own download files. Those are published for you to use in your own database, not to be loaded through this endpoint.\n- Engine settings, extensions and system catalogues.\n\nAttempts to get around these limits or scan for weaknesses may lead to a block.\n\nIf you need more than this endpoint allows, the entire database is free to download and there are no limits on your own copy.\n\nThe files can also be used where they sit, from your own machine. Parquet files support HTTP range requests, so DuckDB, pyarrow, polars or a browser can query them in place and read only the parts a query needs. Example: `SELECT count(*) FROM read_parquet('https://api.tigzig.com/cricket/v1/download/ball_by_ball.parquet');` All files: https://api.tigzig.com/downloads/cricket\n\n### Scope\n\nMen's and women's international cricket in all three formats, plus the IPL. Everything here\nis Cricsheet-derived; there is no other domestic or franchise cricket yet.\n\n## Source and licence\n\nThe data comes from Cricsheet ([cricsheet.org](https://cricsheet.org)) and is published under the Open Data Commons Attribution License 1.0, ODC-BY ([opendatacommons.org/licenses/by/1-0/](https://opendatacommons.org/licenses/by/1-0/)). The tables here are built from the Cricsheet data and refreshed twice daily.\n\nCoverage note: Cricsheet withholds matches featuring the Afghanistan men's team or played in the Afghanistan Premier League (see [cricsheet.org/withheld-matches](https://cricsheet.org/withheld-matches)). That exclusion is inherited here, so this is not a complete record of men's internationals.\n\nProvided as is. No guarantee of accuracy, completeness or availability, and no support commitment.\n\nTigZig is not affiliated with or endorsed by Cricsheet. Cricsheet is credited as the source of the underlying match data under the terms of the ODC-BY 1.0 licence.\n\nFull terms: **[/terms](https://db-mcp.tigzig.com/terms)**\n\n\n### The tables\n\n`ball_by_ball` is one row per delivery and `match_info` is one row per match,\nand they join on `match_id`. Both hold every format and both genders, so you narrow with\nordinary `WHERE` clauses:\n\n| Column | Values |\n|---|---|\n| `match_type` | `T20`, `ODI`, `TEST`, `IPL` |\n| `gender` | `male`, `female` |\n| `team_type` | `international`, `club` |\n\n*** `match_type = 'T20'` MEANS T20 INTERNATIONALS AND DOES NOT INCLUDE THE IPL. *** They are\nseparate values, so twenty-over cricket of every kind is `match_type IN ('T20','IPL')`. This\nis the one thing on this page that will quietly hand you fewer rows than you expected.\n\n### The slice views\n\nEach combination is published as a view too, if you would rather not write the `WHERE`.\nThey are plain views over those tables and hold no separate data:\n\n`ball_by_ball_t20_men`, `ball_by_ball_t20_women`, `ball_by_ball_odi_men`,\n`ball_by_ball_odi_women`, `ball_by_ball_test_men`, `ball_by_ball_test_women`,\n`ball_by_ball_ipl`, and the seven matching `match_info_*` views.\n\n**Every ball table and view has the same columns**, so a query written against one runs\nagainst any other by changing the name.\n\n`DESCRIBE <table>` gives you the columns and types on either engine. The ball columns are\nexplained under \"Reading the ball columns\" below, and the match_info result columns under\n\"How a result is recorded\".\n\n`match_info` is where who won, by how much, which competition, player of the match and the\nofficials live - none of that is in a ball table. Read \"How a result is recorded\" before\ncounting wins: a super-over match is a TIE, not a win.\n\n### Join example\n\n```sql\nSELECT m.winner, SUM(b.runs_off_bat) FROM ball_by_ball b JOIN match_info m ON b.match_id = m.match_id GROUP BY m.winner\n```\n\n### Before you aggregate\n\nOne thing here will otherwise give you a surprising answer. `team1_icc_type` and `event` live in match_info, not in the ball table. A plain \"top run scorers\" over the ball table pools every level of international cricket, so Associate nations rank alongside Full Members. That is correct data, rarely the intended question. Join to match_info and filter when you mean a subset.\n\n### One asymmetry\n\nStated up front, because it will not be obvious from a row count: match_info and the ball-by-ball tables now cover the same match types, so every match here has deliveries behind it. Counting matches in match_info still will not agree with counting them in ONE ball table, because match_info holds every format at once - filter it by match_type to compare like with like.\n\n### match_type values\n\nUppercase: 'ODI', 'T20', 'TEST' and 'IPL'. match_type = 'Test' matches nothing.\n\n## Field definitions live with Cricsheet\n\n**[cricsheet.org/format/csv_ashwin](https://cricsheet.org/format/csv_ashwin/)**\n\nThat page is the canonical data dictionary for every column in these tables. It is their\ndata and their definitions, and it stays right by definition. Open it before writing anything\nthat depends on what a particular field means.\n\nWhat you get here instead is short per-field descriptions, the join key, worked examples and\nthe traps that bite people. Where the two ever disagree, theirs is correct.\n\n\n## What SQL you can run\n\nRead-only, and wider than most people assume. Rather than probing to find the edges, here is\nthe shape of it.\n\n**Statements.** `SELECT`, `WITH`, `EXPLAIN`, `DESCRIBE`, plus `SHOW TABLES` and\n`SHOW DATABASES`.\n\n**Everything you would normally reach for inside a SELECT works.** CTEs including several\nchained together, subqueries and correlated subqueries, every join type, `GROUP BY`, `HAVING`,\nwindow functions, `FILTER (WHERE ...)`, `CASE`, `UNION` and the other set operations, ordering,\n`LIMIT` and `OFFSET`, and the usual string, date, maths and aggregate functions of whichever\nengine you picked.\n\n**Schema introspection works.** `information_schema`, and the `pg_catalog` views on Postgres.\nSo you can ask the database what it holds without guessing.\n\n**Two limits worth knowing before they surprise you.** A query is capped at 3500 characters,\nmeasured on the DECODED SQL, so something over the line only because of URL encoding will fit\nas a POST. If you need more than that, download the dataset and query it locally with no\nlimits. And a query is stopped if it runs past the time limit.\n\n**If something is refused, the error says why.** The response body names the specific problem,\nand usually the exact character, table or function involved. Read it rather than retrying, and\nnote that some HTTP clients hide the body by default.\n\n\n## Want the whole table? Download it, do not paginate it\n\nEvery table is published as files, men's and women's alike, refreshed twice daily from this same database.\n\n**`/downloads` on this service** serves that index directly, and the files themselves come from\n**[api.tigzig.com/cricket/v1/download](https://api.tigzig.com/cricket/v1/download)**\n\nPer table as `parquet`, `csv.gz` or `csv.zip`. All files together as `duckdb.zip`,\n`duckdb.gz`, `sqlite.zip` or `sqlite.gz`. Sizes and row counts are at\n`/cricket/v1/downloads/manifest`.\n\n**Name the file you want and that is exactly what you receive**, so\n`/cricket/v1/download/match_info.csv.gz` returns `match_info.csv.gz` and `curl -O` saves it\nunder the right name with no extra flags. The all-tables file is\n`cricket_all_tables.duckdb.zip` and its three siblings. Names are case-sensitive and nothing\nis inferred, so a wrapping we do not list is a 404 rather than a guess.\n\nPulling a few thousand rows over SQL is exactly what this API is for. Pulling millions is\nslower for you, costs a lot of requests, and gives you something a single file would have\ngiven you in one. The licence is the same either way - see `/terms`.\n\n\n## Is this data right? The checks are published\n\nEvery layer that puts this data behind the API is checked on a schedule and published, pass\nor fail, at **[validation.tigzig.com](https://validation.tigzig.com/)** - what cricsheet publishes against\nthe master, the master against what is served, and what the API returns on both engines,\nplus every anomaly the checks find, row by row. `/validations` on this service redirects\nthere. Read it before deciding a number is wrong.\n\n## Reading the ball columns\n\nEvery row is one delivery. Three columns tell you where it sat in the innings.\n\n| Column | What it is |\n|---|---|\n| `innings` | Which innings. 1 or 2 in a limited-overs match, up to 4 in a Test |\n| `over_no` | Which over, counting from 0 |\n| `delivery_in_over` | Which delivery inside that over, counting from 1 |\n\nAn over usually has six deliveries, so `delivery_in_over` usually runs 1 to 6. When a wide or a no-ball is bowled it has to be bowled again, so the over needs extra deliveries to get six legal ones and the count simply keeps going. Overs of 8 or 10 deliveries are ordinary and longer ones exist. There is no fixed ceiling, and it moves as new matches arrive, so take the current one yourself with a `MAX(delivery_in_over)` if you need it.\n\n**So an over is not a fixed number of rows, and a count of deliveries cannot be derived from `over_no` by multiplying.** If you want legal deliveries, `actual_delivery` already counts them.\n\nHere is a real over that needed 11 deliveries because five of them were wides:\n\n| over_no | delivery_in_over | wides |\n|---|---|---|\n| 1 | 1 | |\n| 1 | 2 | |\n| 1 | 3 | 1 |\n| 1 | 4 | 1 |\n| 1 | 5 | 1 |\n| 1 | 6 | |\n| 1 | 7 | 1 |\n| 1 | 8 | |\n| 1 | 9 | 1 |\n| 1 | 10 | |\n| 1 | 11 | |\n\nTo read an innings in the order it was bowled:\n\n```sql\nSELECT over_no, delivery_in_over, striker, bowler, runs_off_bat\nFROM ball_by_ball\nWHERE match_id = 1208612 AND innings = 1\nORDER BY over_no, delivery_in_over\n```\n\n### The older `ball` column\n\nThere is also a `ball` column, kept because it came first and people have queries written against it. It packs the same two numbers into one decimal, so over 1 delivery 3 shows as `1.3`.\n\nIt has a catch worth knowing. The tenth delivery of an over is written `1.10` at the source, and as a decimal that is the same value as `1.1`, which is the first delivery. So in a long over two different deliveries can carry the same `ball` value, and sorting by it puts the tenth delivery in the wrong place.\n\n`over_no` and `delivery_in_over` are whole numbers, so they cannot run into this. Use them whenever the order matters. `ball` is fine for everything else and is not going anywhere.\n\n### Where a column is numbered, the source sent a list\n\nCricsheet sometimes records more than one name in the same slot: an award shared between two\nplayers, a second TV or reserve umpire, a third and fourth on-field umpire. We split those\ninto numbered columns and keep every entry.\n\n    player_of_match1   player_of_match2\n    umpire1  umpire2   umpire3  umpire4\n    tv_umpire1         tv_umpire2\n    reserve_umpire1    reserve_umpire2\n\nThe `1` column is always populated where the source gave anything; the `2` is filled only\nwhen the source listed a second name, so it is usually null. **Read both if you are counting\nawards or officials** - reading only the first quietly drops the other half. Count them\nyourself if you want the scale; it is one query and it changes as new matches arrive.\n\n`player_of_match`, `tv_umpire` and `reserve_umpire` were the old single-value spellings and\nno longer exist. Queries using them fail rather than silently returning one of two.\n\n**What each field MEANS is Cricsheet's definition, not ours** - see the field reference\nabove. The numbering is only how we lay their list out in columns.\n\n### Identifying a single delivery\n\n`match_id` + `innings` + `over_no` + `delivery_in_over` identifies one delivery uniquely. Use those four together as the key when you need to join deliveries, page through them in a stable order, or check you have not double-counted.\n\n`actual_delivery` looks like it should do the same job and does not. It counts LEGAL deliveries, so a wide or a no-ball does not advance it and every extra shares its number with the legal ball that eventually counts. That is correct behaviour for what the column means, and it is why it repeats.\n\n\n\n## How a result is recorded\n\n**Canonical field definitions live with the source:\n[cricsheet.org/format/csv_ashwin](https://cricsheet.org/format/csv_ashwin/)** - that page is\nthe authority for every column below and is worth opening before you write anything that\ndepends on one. The notes here are short on purpose.\n\n**Read this part even if you skip the rest.** A super-over win is NOT a win. The match is a\ntie and the tiebreak is recorded beside it, which is how the sport itself records it\n(ESPNcricinfo writes it Tie+W / Tie+L). So `eliminator` is a SUBSET of `outcome='tie'`, not a\ncategory next to it, and the partition that always closes is:\n\n```\nwinner IS NOT NULL  +  outcome='draw'  +  outcome='tie'  +  outcome='no result'  =  every match\n```\n\nThere is deliberately no merged \"who really won\" column. Folding super-over wins into wins\nwould promote ties to wins, which is a judgement the sport declines to make. Three plain\npredicates cover every question instead:\n\n```sql\nWHERE winner = 'India'                            -- won outright\nWHERE outcome = 'tie' AND eliminator = 'India'    -- tied, took the tiebreak\nWHERE outcome = 'no result'                       -- abandoned\n```\n\n| Column | What it holds |\n|---|---|\n| `outcome` | `draw`, `tie` or `no result`. Empty when there is a winner |\n| `eliminator` | Team that won the super over. Spelled exactly as `team1` / `team2`, so it joins |\n| `bowl_out` | Team that won the bowl-out. Same spelling rule. Two matches, both T20 |\n| `winner_innings` | `1` when the win was by an innings. **Test only, empty everywhere else** |\n| `method` | `D/L` and similar. Set when the result came from a method rather than play |\n| `super_over` | Which innings numbers were super overs, e.g. `3,4`. One match ran to `3,4,5,6,7,8` |\n| `declared` | Which innings were declared, e.g. `1` or `1,3` |\n| `overs` | Scheduled overs per innings |\n| `target_runs` | Runs the chasing side needs **to win**. The +1 is already in it |\n| `target_overs` | Overs available to the chasing side, when a limit was set |\n| `balls_per_over` | Normally 6 |\n| `match_type_number`, `team_type`, `toss_uncontested` | See the Cricsheet page |\n\n**Four traps worth naming.** Each one returns a number rather than an error, which is why\nthey are here.\n\n`target_runs` ALREADY INCLUDES THE +1. It is the runs needed **to win**, not the runs the\nfirst side made. Chasing 288 gives `target_runs` 289, so the test for a completed chase is\n`cumulative >= target_runs` with nothing added. Adding one yourself moves every answer by a\nrun and nothing complains. Almost every match with a target follows the plus-one rule\nexactly; the handful that do not are rain-revised.\n\n`target_runs` IS NOT ONLY FOR RAIN-AFFECTED GAMES, which this page used to say. The great\nmajority of matches carrying a target have **no `method` at all**, so it is the ordinary\ntarget on any chase. `method` is what tells you one was revised.\n\n`winner_innings` IS EMPTY ON EVERY LIMITED-OVERS MATCH. It appears on Test matches only and\non **no** ODI, T20 or IPL match at all, because an innings victory cannot happen there. The\nname suggests a batting order and it is not that - it is a victory MARGIN flag. If you want\n\"did the side batting second win\", the test is `winner_wickets IS NOT NULL`, which is exact:\n`winner_runs` and `winner_wickets` never both appear on the same match.\n\n`winner_runs` alone is ambiguous. With `winner_innings = 1` a value of 359 means \"by an\ninnings and 359 runs\", not \"by 359 runs\". Ordering by `winner_runs` without checking\n`winner_innings` gives a wrong ranking and no error.\n\n`target_overs` is overs-and-balls, not a decimal. `40.2` is 40 overs and 2 balls, so averaging\nor summing that column produces a number that means nothing.\n\n**One column is ours, not Cricsheet's.** `team1_icc_type` / `team2_icc_type` are our mapping,\ntaken from the ICC Classification of Official Cricket with effect from 1 July 2026:\n[the classification document](https://images.icc-cricket.com/image/upload/prd/enzawp3xa8h4ahqonlpd.pdf),\nreached from the ICC's [playing conditions page](https://www.icc-cricket.com/about/cricket/rules-and-regulations/playing-conditions).\nThe document is the source; the page carries the surrounding regulations.\n\n**Men's and women's ODI status are different lists, and we map them separately.** A team can\nhold one and not the other, so the value depends on the match's `gender` as well as the team.\n\nTwo caveats, both ours to state. It is a **snapshot applied to every match regardless of\ndate**, so it is not the team's status on the day - Ireland appear as a Full Member in\nfixtures played years before they became one, and the ICC's own document says the\nclassification is not intended to be applied retrospectively. And it moves when the ICC\nrepublishes. Check the document above if a value matters to your result.\n\n## SQL guardrails\n\nRead-only endpoint.\n\n### Statements\n\n- `SELECT` and `WITH`.\n- `SHOW TABLES`, `DESCRIBE <name>` and `EXPLAIN`. `DESCRIBE` is the quickest way to get column types, and both work on either engine.\n- One statement per request. A semicolon-separated batch is rejected rather than running only the last one.\n\n### Clauses and operators\n\n- `JOIN` with an explicit `ON`, up to 10 per SELECT\n- `WHERE`, `GROUP BY`, `HAVING`, `ORDER BY`, `LIMIT`, `OFFSET`\n- `CASE WHEN`, `DISTINCT`, `IN`, `EXISTS`, `BETWEEN`, `LIKE`, `ILIKE`, `IS NULL`\n- `UNION` and `UNION ALL`\n- Subqueries to depth 3. CTEs do not count towards that depth, so a chain of CTEs can go deeper.\n- Window functions: `OVER (PARTITION BY ... ORDER BY ...)`, window frames such as `ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW`, `FILTER (WHERE ...)`, and `QUALIFY`\n- Arithmetic and comparison operators\n\n### Functions\n\nIf a function is not on this list, it is not available.\n\n| | |\n|---|---|\n| Aggregate | `count` `sum` `min` `max` `avg` `median` `mode` `stddev` `stddev_pop` `stddev_samp` `variance` `var_pop` `var_samp` `percentile_cont` `percentile_disc` `quantile_cont` `quantile_disc` `count_if` `arg_min` `arg_max` `max_by` `any_value` `array_agg` `string_agg` `group_concat` |\n| Boolean aggregate | `bool_and` `bool_or` `every` |\n| Window | `row_number` `rank` `dense_rank` `percent_rank` `cume_dist` `ntile` `lag` `lead` `first_value` |\n| Numeric | `floor` `ceil` `ceiling` `round` `abs` `sign` `sqrt` `greatest` `least` |\n| Null handling | `coalesce` `nullif` |\n| Type conversion | `cast` `try_cast` |\n| Date | `extract` `year` `month` `day` `date_part` |\n| Text | `length` `lower` `upper` `split_part` |\n\nFor case-insensitive matching you do not need a function at all: `ILIKE` is available and\nis usually the better answer.\n\n`string_agg` and `group_concat` are the same function under two names and both work, on\nwhichever engine has them - `group_concat` is a DuckDB spelling, so on Postgres use\n`string_agg`.\n\n`percentile_cont` and `percentile_disc` use the ordered-set form and work on both engines:\n`percentile_cont(0.5) WITHIN GROUP (ORDER BY runs_off_bat)`. `quantile_cont` and\n`quantile_disc` are the DuckDB spellings and Postgres does not have them.\n\n### Tables\n\n- The cricket tables listed above.\n- `information_schema` and `pg_class`, for schema metadata. Both list the cricket tables above, so you can ask the database what it holds rather than guessing.\n\n### Also blocked\n\n- Writes and DDL of any kind.\n- SQL comments.\n- `INTERSECT` and `EXCEPT`.\n- Joins without `ON`, comma joins, `CROSS JOIN`.\n- More than 10 JOINs per SELECT.\n- More than 10 SELECT keywords, counting the word SELECT anywhere in the query, including inside CTEs and subqueries.\n- `WITH RECURSIVE`.\n- Subqueries inside `ORDER BY`, and function calls inside `ORDER BY`. Sort on a plain column, or compute the value in a SELECT or CTE first and sort on that.\n- Functions that read a file or a URL.\n- `COPY`, in any form.\n- Queries longer than 3500 characters. The limit is measured on the decoded SQL, so a GET that is over only because of URL encoding will fit if sent as a POST with a JSON body.\n\n### Row limit: every query returns at most 1000 rows\n\n- If yours would return more, you get the first 1000 and `truncated: true`. Always read that field.\n- The ceiling applies even when you ask for more: `LIMIT 5000` returns 1000 rows with `truncated: true`, not 5000.\n- A `LIMIT` or `FETCH FIRST` below 1000 is honoured exactly and comes back `truncated: false`, so you know you have the whole result.\n- If you set no limit at all, one is added for you. Everything else behaves normally: `ORDER BY`, `OFFSET`, CTEs and aggregates are unaffected, so `LIMIT ... OFFSET ...` pagination works.\n- **Set your own limit.** It is faster, and a `false` on `truncated` is your proof nothing was cut.\n- There is also a 256KB response limit.\n\n### Response format: `json`, `csv` or `tsv`\n\n- Pass `format` in the JSON body, or as a query parameter on a GET. The default is `json`.\n- `json` returns `columns` plus `rows` as arrays.\n- `csv` and `tsv` return the rows as a plain file with a header row, ready to save or read straight into a dataframe. There is no JSON to unwrap.\n- Any other value is treated as `json`.\n\nOn `csv` and `tsv` the row count and the truncation flag move to response headers, because they cannot sit in the file without breaking it. Read `X-Row-Count` and `X-Truncated`. A `true` there means the row cap cut your result, and the `Link` header points at the bulk download.\n\nErrors are always `json`, whatever format you asked for. So check the status code first: a 200 is your data in the format you requested, and anything else is a JSON body explaining why.\n\n\n### Time limit: 15s per query\n\nA query that runs past the limit is cancelled. Disconnecting does not stop a running query, so do not resend while one is running. If a query needs longer, download the whole database and run it locally with no time limit.\n\n### Two engines, two dialects\n\n`/v1/query/postgres` is PostgreSQL and `/v1/query/duckdb` is DuckDB. **They hold the same tables** - `ball_by_ball`, `match_info`, `match_players`, `people` and a view for each slice - with the same rows and the same columns, so the endpoint you choose is a choice of SQL DIALECT and nothing else. Ask either one the same question and you get the same answer.\n\nThe dialects are **not** interchangeable, and that is the only thing that differs. Each supports functions and syntax the other does not: `QUALIFY` works on DuckDB and fails on Postgres, and date and string functions differ. So if a query works on one endpoint and fails on the other, **it is the dialect, not the table** - the table is present on both. Standard `SELECT`, `JOIN`, `GROUP BY`, CTEs, window functions and `FILTER` work on both.\n\n## When a query fails\n\n### Read the SQL we quote back to you\n\nEvery error repeats the SQL exactly as we received it. Compare that against what you sent.\nIf the two differ, the problem is not your SQL, it is what happened to it on the way here,\nand the next section is for you. This one check settles most failures in seconds.\n\n### The URL can change your SQL without telling you\n\nThis affects GET only, where the query travels inside the URL and your client has to\npercent-encode it. When that encoding is incomplete, the SQL that arrives is not the SQL\nyou wrote. Three real examples, all from live traffic:\n\n| You wrote | We received | Cause |\n|---|---|---|\n| `SUM(runs_off_bat + extras)` | `SUM(runs_off_bat   extras)` | A bare `+` in a URL means space. Send `%2B` |\n| `... AS runs FROM ball_by_ball` | `... AS runsFROM ball_by_ball` | A line break was swallowed |\n| `SELECT gender, COUNT(*) FROM ...` | `SELECT gender, COUNT` | The encoder gave up at `(` |\n\nIn all three cases the caller was looking at correct SQL and being told it was invalid.\n\n**The fix for all of them is the same: send the query as a POST with a JSON body.**\n\n```bash\ncurl -X POST \"https://db-mcp.tigzig.com/v1/query/duckdb\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"sql\": \"SELECT COUNT(*) AS balls FROM ball_by_ball\", \"format\": \"json\"}'\n```\n\nA JSON body has no percent-encoding step to get wrong, and the length limit is measured on\nthe decoded SQL, so a query that is over the limit as a GET may be comfortably under it as\na POST. GET stays fully supported and is the right choice from a browser or a no-code HTTP\nnode. If you use it, percent-encode the whole query, including `+` as `%2B`.\n\n### Which error you got tells you where to look\n\n- `SQL_REJECTED` means this endpoint refused the query before running it. The reason is in\n  the message, and everything we refuse is listed under SQL guardrails above.\n- `SQL_ERROR` means the database itself rejected it. That is an ordinary SQL problem: a\n  wrong column, an ambiguous reference, something missing from `GROUP BY`. The database's\n  own message is passed through unchanged.\n\n### One note on retrying\n\nIf a query is slow, wait for it to come back rather than firing it again. Disconnecting\ndoes not stop it, so wait for the result before sending it again.\n\n## Data semantics\n\nEach row is a single delivery (ball) in a match, in whichever ball table you queried. The shape of a match follows the FORMAT, not the endpoint: an ODI is 50 overs per innings and a T20 is 20, usually 2 innings each. Both tables are on both engines, so pick the table for the format you want.\n\n### Ball counting\n\nThe ball field (e.g. 0.1, 7.5) is an over.ball identifier, NOT a sequential count. Overs may have >6 deliveries due to wides/no-balls (e.g. 0.7). Use COUNT(*) for total balls bowled.\n\n**To get the over number, use `FLOOR(ball)`, not `CAST(ball AS INTEGER)`.** The field is stored as a floating-point number, and a cast to integer ROUNDS rather than truncates on both engines: `CAST(19.5 AS INTEGER)` is 20, while `FLOOR(19.5)` is 19. A cast therefore moves every delivery from x.5 onwards into the next over. Nothing errors when this happens - the query succeeds and the totals look plausible - and it distorts precisely the deliveries at the end of an innings. `MAX(FLOOR(ball))` gives the last over bowled and `COUNT(DISTINCT FLOOR(ball))` the number of overs.\n\n### Runs\n\n`runs_off_bat` is runs scored by batsman. extras = additional runs (wides, no-balls, byes, legbyes, penalty). Total runs for a delivery = runs_off_bat + extras. NULL extras components should be treated as 0.\n\n### Wickets\n\nCheck both wicket_type AND other_wicket_type for dismissals. If either is non-null, that delivery has a dismissal. Common wicket_type values: bowled, caught, lbw, run out, stumped, caught and bowled, hit wicket, retired hurt.\n\n### Player names\n\nUse the exact full name if known. If uncertain, use surname with LIKE wildcards (e.g. WHERE striker LIKE '%Kohli%').\n\n### Season format\n\nCan be a year (2023) or split-year (2023/24) for southern hemisphere seasons.\n\n### match_type\n\nScoped to the TABLE, not to the endpoint. Every row carries its own `match_type`, on BOTH engines - so filtering a ball table by match_type is always a no-op. It is only meaningful on `match_info`, which carries all three formats including TEST.\n\n### Example query\n\n```sql\nSELECT striker, SUM(runs_off_bat) as runs, COUNT(*) as balls FROM ball_by_ball WHERE season = '2023' GROUP BY striker ORDER BY runs DESC LIMIT 10\n```\n\nPart of Tigzig: free interactive tools, open-source repos, APIs and MCP servers for\nanalytics and live data across global and Indian markets, macro indicators and\nfilings. Catalog: https://api.tigzig.com/.well-known/api-catalog\nGuide: https://www.tigzig.com/llms.txt","version":"1.0.0"},"paths":{"/downloads":{"get":{"summary":"Bulk file downloads for the cricket data","description":"Whole tables as files, for when paginating a large result out of the SQL endpoints is the wrong tool.\n\n**The URL ends in the filename you get**, so `curl -O` and `wget` save it under that name with no extra flags:\n\n```\nhttps://db-mcp.tigzig.com/downloads/match_info.parquet\nhttps://db-mcp.tigzig.com/downloads/cricket_all_tables.duckdb.zip\n```\n\n**Tables:** `ball_by_ball`, `match_info`, plus a view per slice\n\n**Per table:** `.parquet`, `.csv.gz`, `.csv.zip`\n\n**Everything together:** `cricket_all_tables` with `.duckdb.zip`, `.duckdb.gz`, `.sqlite.zip` or `.sqlite.gz`. Also `README.txt`.\n\nNames are case-sensitive and nothing is inferred, so a wrapping we do not list is a 404 rather than a guess. For the current list with sizes and row counts, call `/downloads` with no filename.\n\nThe same ODC-BY licence applies - see `/terms`.\n\n*Note: the files are served from the Tigzig file service and the per-file URLs redirect there, so either host works. `https://api.tigzig.com/cricket/v1/download/match_info.parquet` is the same file.*","operationId":"bulk_downloads","responses":{"302":{"description":"Redirect to the file service. Same document at the target."},"200":{"description":"The download index, served directly. One hop, no redirect."}}}},"/validations":{"get":{"summary":"Where the data-quality checks on this data are published","description":"Redirects to **validation.tigzig.com**, where every layer that puts this data behind the API is checked on a schedule and published, pass or fail: what cricsheet publishes against the master, the master against what is served, and what the API returns on both engines. Plus every anomaly the checks find, row by row, with the explanation where there is one.\n\nAgents: the same content as markdown is at `https://validation.tigzig.com/index.md` and `https://validation.tigzig.com/anomalies.md`.","operationId":"validation_page","responses":{"302":{"description":"Successful Response"}}}},"/v1/query/postgres":{"post":{"summary":"Run read-only SQL on Postgres: men's and women's T20, ODI and Test internationals, plus the IPL cricket ball-by-ball","description":"Run read-only SQL against the cricket data. **PostgreSQL dialect.**\n\nTables: `ball_by_ball`, `ball_by_ball_ipl`, `ball_by_ball_odi_men`, `ball_by_ball_odi_women`, `ball_by_ball_t20_men`, `ball_by_ball_t20_women`, `ball_by_ball_test_men`, `ball_by_ball_test_women`, `match_info`, `match_info_ipl`, `match_info_odi_men`, `match_info_odi_women`, `match_info_t20_men`, `match_info_t20_women`, `match_info_test_men`, `match_info_test_women`, `match_players`, `people`\n\nAt most 1,000 rows per query and 3,500 characters of SQL. Send a POST with a JSON body -\na GET has to be percent-encoded, and that is the commonest reason a query arrives different\nfrom the one you wrote.\n\nThe tables, the columns, the SQL guardrails and the traps are documented once at the top of\nthis page and apply to both engines.","operationId":"query_postgres","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryRequest"},"examples":{"cricket":{"summary":"Top ODI run-scorers in the 2023 season","value":{"sql":"SELECT striker, SUM(runs_off_bat) AS runs, COUNT(*) AS balls FROM ball_by_ball WHERE season = '2023' GROUP BY striker ORDER BY runs DESC LIMIT 10","format":"json"}}}}}},"responses":{"200":{"description":"Rows, in the requested format. `format=json` returns `rows` as arrays positioned against `columns`; `format=tsv` returns the whole table as one `data` string whose header row carries the SAME column names as `format=json`. ALWAYS read `truncated` - true means the row cap was hit and you are seeing a prefix.","content":{"application/json":{"schema":{"type":"object","required":["format","columns","row_count","truncated"],"properties":{"format":{"type":"string","enum":["json","csv","tsv"],"description":"Echoes the format you asked for."},"columns":{"type":"array","items":{"type":"string"},"description":"Column names in select-list order. Identical for format=json and format=tsv."},"rows":{"type":"array","items":{"type":"array"},"description":"format=json ONLY. One array per row, values positioned against `columns`."},"data":{"type":"string","description":"format=tsv ONLY. The whole table, tab-separated, header row first, newline terminated."},"column_mapping":{"type":"object","additionalProperties":{"type":"string"},"description":"format=tsv ONLY. Kept for compatibility; an identity map."},"row_count":{"type":"integer","description":"Rows in THIS response, after the cap is applied."},"truncated":{"type":"boolean","description":"True when the row cap was hit and rows were dropped. Always read this."},"hint":{"type":"string","description":"Present ONLY when `truncated` is true. Names the row cap and points at the bulk download, which has no row cap, no rate limit and no query length cap."}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"summary":"GET variant: read-only SQL on Postgres (men's and women's T20, ODI and Test internationals, plus the IPL) via ?sql=","description":"GET variant for fetch-only clients (browsers, crawler-style agents, no-code HTTP nodes that cannot send a POST body). Same engine, same read-only SQL validation, same row/size caps, timeouts and rate limits as the POST endpoint - the SQL simply arrives in the `sql` query parameter (URL-encoded; `query` also works as an alias), with optional `format=json|tsv`. POST remains the primary interface and is better for long SQL (no URL-length limit).\n\n**If your SQL fails here and looks correct, suspect the URL encoding before the SQL.** A bare `+` arrives as a space, line breaks can be swallowed, and a partial encoder can truncate the query - so what we receive is not what you sent. Send `+` as `%2B`, or use POST and avoid the problem entirely. Worked examples of all three are under \"When a query fails\" on the POST operation for this endpoint.","operationId":"query_postgres_get","parameters":[{"name":"sql","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Read-only SQL SELECT, URL-encoded.","examples":["SELECT COUNT(*) AS balls FROM ball_by_ball_t20_men"],"title":"Sql"},"description":"Read-only SQL SELECT, URL-encoded."},{"name":"query","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Alias for `sql` - either parameter works.","title":"Query"},"description":"Alias for `sql` - either parameter works."},{"name":"format","in":"query","required":false,"schema":{"type":"string","description":"json (default), csv or tsv. csv and tsv return a plain file with a header row; row_count and truncated move to the X-Row-Count and X-Truncated headers. Errors are always json.","enum":["json","csv","tsv"],"default":"json","title":"Format"},"description":"json (default), csv or tsv. csv and tsv return a plain file with a header row; row_count and truncated move to the X-Row-Count and X-Truncated headers. Errors are always json."}],"responses":{"200":{"description":"Rows, in the requested format. `format=json` returns `rows` as arrays positioned against `columns`; `format=tsv` returns the whole table as one `data` string whose header row carries the SAME column names as `format=json`. ALWAYS read `truncated` - true means the row cap was hit and you are seeing a prefix.","content":{"application/json":{"schema":{"type":"object","required":["format","columns","row_count","truncated"],"properties":{"format":{"type":"string","enum":["json","csv","tsv"],"description":"Echoes the format you asked for."},"columns":{"type":"array","items":{"type":"string"},"description":"Column names in select-list order. Identical for format=json and format=tsv."},"rows":{"type":"array","items":{"type":"array"},"description":"format=json ONLY. One array per row, values positioned against `columns`."},"data":{"type":"string","description":"format=tsv ONLY. The whole table, tab-separated, header row first, newline terminated."},"column_mapping":{"type":"object","additionalProperties":{"type":"string"},"description":"format=tsv ONLY. Kept for compatibility; an identity map."},"row_count":{"type":"integer","description":"Rows in THIS response, after the cap is applied."},"truncated":{"type":"boolean","description":"True when the row cap was hit and rows were dropped. Always read this."},"hint":{"type":"string","description":"Present ONLY when `truncated` is true. Names the row cap and points at the bulk download, which has no row cap, no rate limit and no query length cap."}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/query/duckdb":{"post":{"summary":"Run read-only SQL on DuckDB: men's and women's T20, ODI and Test internationals, plus the IPL cricket ball-by-ball","description":"Run read-only SQL against the cricket data. **DuckDB dialect.**\n\nTables: `ball_by_ball`, `ball_by_ball_ipl`, `ball_by_ball_odi_men`, `ball_by_ball_odi_women`, `ball_by_ball_t20_men`, `ball_by_ball_t20_women`, `ball_by_ball_test_men`, `ball_by_ball_test_women`, `match_info`, `match_info_ipl`, `match_info_odi_men`, `match_info_odi_women`, `match_info_t20_men`, `match_info_t20_women`, `match_info_test_men`, `match_info_test_women`, `match_players`, `people`\n\nAt most 1,000 rows per query and 3,500 characters of SQL. Send a POST with a JSON body -\na GET has to be percent-encoded, and that is the commonest reason a query arrives different\nfrom the one you wrote.\n\n`QUALIFY` works here and not on Postgres. That dialect difference is the only thing\nseparating the two endpoints; the data behind them is identical.\n\nThe tables, the columns, the SQL guardrails and the traps are documented once at the top of\nthis page and apply to both engines.","operationId":"query_duckdb","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryRequest"},"examples":{"cricket":{"summary":"Top T20 run-scorers in the 2023 season","value":{"sql":"SELECT striker, SUM(runs_off_bat) AS runs, COUNT(*) AS balls FROM ball_by_ball WHERE season = '2023' GROUP BY striker ORDER BY runs DESC LIMIT 10","format":"json"}}}}}},"responses":{"200":{"description":"Rows, in the requested format. `format=json` returns `rows` as arrays positioned against `columns`; `format=tsv` returns the whole table as one `data` string whose header row carries the SAME column names as `format=json`. ALWAYS read `truncated` - true means the row cap was hit and you are seeing a prefix.","content":{"application/json":{"schema":{"type":"object","required":["format","columns","row_count","truncated"],"properties":{"format":{"type":"string","enum":["json","csv","tsv"],"description":"Echoes the format you asked for."},"columns":{"type":"array","items":{"type":"string"},"description":"Column names in select-list order. Identical for format=json and format=tsv."},"rows":{"type":"array","items":{"type":"array"},"description":"format=json ONLY. One array per row, values positioned against `columns`."},"data":{"type":"string","description":"format=tsv ONLY. The whole table, tab-separated, header row first, newline terminated."},"column_mapping":{"type":"object","additionalProperties":{"type":"string"},"description":"format=tsv ONLY. Kept for compatibility; an identity map."},"row_count":{"type":"integer","description":"Rows in THIS response, after the cap is applied."},"truncated":{"type":"boolean","description":"True when the row cap was hit and rows were dropped. Always read this."},"hint":{"type":"string","description":"Present ONLY when `truncated` is true. Names the row cap and points at the bulk download, which has no row cap, no rate limit and no query length cap."}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"summary":"GET variant: read-only SQL on DuckDB (men's and women's T20, ODI and Test internationals, plus the IPL) via ?sql=","description":"GET variant for fetch-only clients (browsers, crawler-style agents, no-code HTTP nodes that cannot send a POST body). Same engine, same read-only SQL validation, same row/size caps, timeouts and rate limits as the POST endpoint - the SQL simply arrives in the `sql` query parameter (URL-encoded; `query` also works as an alias), with optional `format=json|tsv`. POST remains the primary interface and is better for long SQL (no URL-length limit).\n\n**If your SQL fails here and looks correct, suspect the URL encoding before the SQL.** A bare `+` arrives as a space, line breaks can be swallowed, and a partial encoder can truncate the query - so what we receive is not what you sent. Send `+` as `%2B`, or use POST and avoid the problem entirely. Worked examples of all three are under \"When a query fails\" on the POST operation for this endpoint.","operationId":"query_duckdb_get","parameters":[{"name":"sql","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Read-only SQL SELECT, URL-encoded.","examples":["SELECT COUNT(*) AS balls FROM ball_by_ball_t20_men"],"title":"Sql"},"description":"Read-only SQL SELECT, URL-encoded."},{"name":"query","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Alias for `sql` - either parameter works.","title":"Query"},"description":"Alias for `sql` - either parameter works."},{"name":"format","in":"query","required":false,"schema":{"type":"string","description":"json (default), csv or tsv. csv and tsv return a plain file with a header row; row_count and truncated move to the X-Row-Count and X-Truncated headers. Errors are always json.","enum":["json","csv","tsv"],"default":"json","title":"Format"},"description":"json (default), csv or tsv. csv and tsv return a plain file with a header row; row_count and truncated move to the X-Row-Count and X-Truncated headers. Errors are always json."}],"responses":{"200":{"description":"Rows, in the requested format. `format=json` returns `rows` as arrays positioned against `columns`; `format=tsv` returns the whole table as one `data` string whose header row carries the SAME column names as `format=json`. ALWAYS read `truncated` - true means the row cap was hit and you are seeing a prefix.","content":{"application/json":{"schema":{"type":"object","required":["format","columns","row_count","truncated"],"properties":{"format":{"type":"string","enum":["json","csv","tsv"],"description":"Echoes the format you asked for."},"columns":{"type":"array","items":{"type":"string"},"description":"Column names in select-list order. Identical for format=json and format=tsv."},"rows":{"type":"array","items":{"type":"array"},"description":"format=json ONLY. One array per row, values positioned against `columns`."},"data":{"type":"string","description":"format=tsv ONLY. The whole table, tab-separated, header row first, newline terminated."},"column_mapping":{"type":"object","additionalProperties":{"type":"string"},"description":"format=tsv ONLY. Kept for compatibility; an identity map."},"row_count":{"type":"integer","description":"Rows in THIS response, after the cap is applied."},"truncated":{"type":"boolean","description":"True when the row cap was hit and rows were dropped. Always read this."},"hint":{"type":"string","description":"Present ONLY when `truncated` is true. Names the row cap and points at the bulk download, which has no row cap, no rate limit and no query length cap."}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/terms":{"get":{"summary":"Licence and source for the cricket data","description":"Plain-text licence, source and coverage for the cricket data, covering every route it is served by: the REST API, the MCP tools and the bulk file downloads. Fetch this rather than paraphrasing it. Also at /v1/terms.","operationId":"data_terms","responses":{"200":{"description":"Successful Response","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/health":{"get":{"summary":"Health check","description":"Health check.","operationId":"health_check","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"QueryRequest":{"properties":{"sql":{"type":"string","title":"Sql"},"format":{"type":"string","title":"Format","default":"json"}},"type":"object","required":["sql"],"title":"QueryRequest"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}