Data.Readme: Documenting Table Relationships for Diverse Data Tasks

ACM Reference Format:

Jiaming Liang, Yeye He, Haoyu Dong, Zachary Ives, and Surajit Chaudhuri. 2027. Data.Readme: Documenting Table Relationships for Diverse Data Tasks. In Proceedings of SIGMOD Conference on Management of Data (SIGMOD ’27). ACM, New York, NY, USA, 14 pages. https://doi.org/XXXXXXX. XXXXXXX

Permission to make digital or hard copies of all or part of this work for personal or classroom use is granted without fee provided that copies are not made or distributed for profit or commercial advantage and that copies bear this notice and the full citation on the first page. Copyrights for components of this work owned by others than the author(s) must be honored. Abstracting with credit is permitted. To copy otherwise, or republish, to post on servers or to redistribute to lists, requires prior specific permission and/or a fee. Request permissions from [email protected]. SIGMOD ’27, Huntington Beach, CA, USA © 2027 Copyright held by the owner/author(s). Publication rights licensed to ACM. ACM ISBN 978-x-xxxx-xxxx-x/YYYY/MM https://doi.org/XXXXXXX.XXXXXXX

Introduction

Large language models (LLMs) are increasingly capable of performing diverse tasks over tabular data, when given a small set of tables relevant to a task [31, 34]. However, users often need to perform data discovery, data analysis, and data science over a large data lake containing thousands of tables, without knowing in advance which tables are relevant [21, 23]. Such tasks remain challenging for today’s models and agentic harnesses [29, 44].

Consider a concrete example data lake tested in our experiments, illustrated in Figure 1. It contains 17 tables named “Sales,” 29 named “Customers,” and 21 named “Country,” many with similar schemas. To answer a question such as “global sales by customer country” in a particular region and time period, a human or LLM agent must determine not only which Sales table is relevant, but also which Customers and Country tables can be “paired/joined” with that Sales table to answer the question, which is unfortunately non-trivial in a large data lake, as table and schema names alone provide little clue for LLM to identify relevant tables.

Therefore, today existing methods (including powerful data agents and coding agents [2, 3, 4]) are often forced to open and explore a large number of tables that may be relevant at online query time, (e.g., all 17 Sales tables and all 29 Customers tables) before locating the ones relevant for a task. This approach is clearly (1) time-consuming, because users must wait while the agent explores the data; (2) less accurate, because the agent must often decide using partial, shallow evidence collected at runtime; and (3) wasteful, as each new question triggers another expensive round of exploration from scratch whose findings are seldom reused.

README for codebases vs. README for data lakes. We draw inspiration from software engineering, where humans and LLMs face a similar readability/discoverability problem in complex codebases, which is commonly addressed with a README [5] and, increasingly, an AGENTS.md for LLM agents [1]. Placed at the root of a repository, these readme documents explain what the code does and how its components relate to each other with navigatable links, allowing developers and agents to reuse knowledge rather than rediscover it from scratch.

This analogy motivates our core research question: Can a README-equivalent for tables benefit data agents operating over data lakes, just as READMEs benefit coding agents operating over codebases?

DATA.README for tables: relationships beyond simple summaries. A natural first step in documenting a dataset is to prompt an LLM to summarize each table and column in natural language, as used in recent work such as AutoDDG [53].

While such approaches are clearly useful, we observe that freeform descriptions of individual tables are insufficient for many complex data tasks, which often depend on table-to-table relationships, and would benefit from a more structured and holistic view of the lake. This resembles how a codebase README would not only describe files in isolation, but also use pointers and hyperlinks to connect related components. We illustrate this with an example.

In this work we study the Data.README framework using three example types of table-relationships (extensible to additional types): (1) confusable tables, which look similar but differ in grain, geography, time period, aggregation level, or other properties; (2) joinable tables, which have a meaningful semantic join rather than an accidental overlap in key ranges; and (3) union-able tables, which share a compatible schema.

We aim to show that, at the framework level, plugging in different types of relationships can bring substantial quality and latency benefits for diverse agent tasks operating on large data lakes. While we present efficient techniques for extracting these relationships that can scale to large lakes, our goal is not to establish new state-of-the-art methods for each individual relationship type, which has a literature of its own. Instead, the framework is designed to accommodate alternative methods, allowing individual components to be readily replaced as better techniques emerge.

Technical challenges. Producing this documentation for tens of thousands of tables raises challenges that a per-table annotation method like AutoDDG [53] does not face.

Efficient extraction of relationships: The number of possible relationships grows quadratically with the number of tables, where processing using LLM calls can become expensive very quickly. We develop extraction algorithms that scale linearly with the number of tables, or even sub-linearly if there is a fixed cost budget.

Resolving semantic ambiguity: At scale, determining whether two tables are meaningfully related (e.g., confusable or joinable) becomes increasingly challenging and ambiguous. We develop data-driven techniques to resolve such ambiguities while adopting a late-binding strategy that retains plausible relationships until query time, when the user’s question can provide additional evidence for disambiguation.

Agentic tools for Data.README: In a large lake, even concise documentation such as Figure 1(b) may exceed an agent’s context window. We develop tools that let an agent navigate the Data.README index efficiently (e.g., retrieving tables relevant to a query by RAG-top-k, or jumping to tables with known relationships to a target table by name). Our experiments show that these capabilities are effective and necessary to scale to large lakes.

Budget-constrained optimization: Despite our efficient, lightweight indexing, processing every table in a large lake may still be costly. We therefore formulate the Budget-Constrained Table Documentation (BCTD) problem, where given a fixed budget and a representative query log, we want to identify a subset of tables for processing that are most beneficial for the query workload. While we prove that the problem is computationally hard, we develop a fast density-based algorithm called DensitySelect, which has provable approximation guarantees and is effective in experiments.

Contributions. We make the following contributions:

• We propose Data.README, structured documentation for data lakes that augments per-table descriptions with cross-table relationships such as confusable, joinable, and union-able tables. We also provide agentic tools that make this information easily accessible and navigable to LLMs (§ 2).

• We develop lightweight, scalable approaches for extracting these relationships, with a bounded linear construction cost despite the quadratic growth in possible table pairs (§ 3).

• We formulate the budget-constrained scenario as a principled optimization problem, and develop DensitySelect, a density-based algorithm with approximation guarantees (§ 4).

• We evaluate Data.README on diverse tasks such as data discovery, data analysis, and data science. Across 96 experimental settings (2 lakes × 6 backbone models × 8 benchmark tasks), Data.README outperforms diverse baselines including strong coding agents in 92 out of the 96 settings, all while operating at reduced cost/latency. (§ 5).

Preliminaries and Problem Statement

Preliminaries

Data lake. Let $\mathcal{L} = \{T_1, \ldots, T_n\}$ denote a collection of tables, each with a unique identifier, a schema and accessible rows. For instance, in Example 1, we may encounter the many similarly-named tables (Sales, Customers, Country, etc.) in a multi-national’s data lake, which can arise from different regional systems, historical sales records, and revenue summaries.

Data tasks on data lakes. Users often need to perform diverse tasks on data lakes with thousands of tables, without knowing in advance which tables in $\mathcal{L}$ are relevant. We consider 3 such tasks in this work: data discovery, data analysis, and data science.

In data discovery, let $Q$ be a user query with the intent to locate relevant tables in $\mathcal{L}$ (e.g., “global sales by customer country since 2024” in Example 1), the goal is to retrieve the relevant set of tables that can be used to answer $Q$ (e.g., $\{\text{Sales\_1}, \text{Sales\_14}, \text{Country\_1}, \text{Customer\_9}\}$ in Example 1).

In data analysis, let $Q$ be a user’s analysis query, and the goal is to answer $Q$ directly by executing Python or SQL code over relevant tables identified from $\mathcal{L}$. Today’s reasoning-capable models can often interleave data discovery and analysis ¹, performing calculations as they explore tables (e.g., different Sales tables), and backtracking in a trial-and-error process, which can lead to very different trajectories compared to pure data discovery above.

In data science, we consider the classical predictive modeling task of using a given target column $C$ in a table $T \in\mathcal{L}$ as the prediction target (which would be a regression task if $C$ is numerical, or a classification task if $C$ is categorical). Agents performing such a predictive task may be able to leverage additional related tables in $\mathcal{L}$ (e.g., via joins or unions), which can boost predictive accuracy.

Problem Statement

In this work, we study the benefit of providing agents with cross-table relationships in data lakes, by extracting 3 example types of common relationships: $\mathcal{R} = \{\text{Confusable}, \text{Joinable}, \text{Union-able}\}$. We study two problem variants, one without budget constraints and one with a fixed budget.

In our example with $\mathcal{R} = \{\text{Confusable}, \text{Joinable}, \text{Union-able}\}$, for each $T_i \in\mathcal{L}$, we use $C(T_i)$, $J(T_i)$, and $U(T_i)$ to denote its Confusable, Joinable, and Union-able relationships, respectively. The relationship $\mathcal{R}(\mathcal{L})$ we want to extract is therefore:

Figure 1(b) shows an example of such extracted relationships, presented in a markdown table format. Given the pairwise nature of cross-table relationships, a key challenge is to produce such relationships accurately and efficiently (without quadratic comparisons), which we discuss in Section 3.

Although our approach solves the problem in Definition 1 efficiently, at a cost as low as one cent per table using LLMs, extracting relationships for every table in large data lakes containing millions of tables may be neither necessary, nor desirable for users with a fixed budget. We therefore also study a budget-constrained variant of the problem, formalized in Definition 2 below, which assumes access to a historical query log $QL$ that is representative of workloads on $\mathcal{L}$.

While we state this budget-constrained version at a high level, we study a concrete combinatorial optimization problem corresponding to this high level definition in § 4, for which we develop approximation algorithms with provable guarantees.

Data.Readme

System Overview

At a high level, Data.Readme aims to build a relationship graph in large data lakes offline, enriched with natural-language context describing how tables differ or relate, which we posit will help agents to better navigate data lakes and perform complex tasks. Figure 1 gives an overview of our proposed Data.Readme system.

In the offline indexing step shown in Figure 1a, we extract three example cross-table relationships, $\mathcal{R} = \{\text{Confusable}, \text{Joinable}, \text{Union-able}\}$ (which are extensible to additional types of relationships), using lightweight processing that scales linearly with the number of tables if there are no budget constraints (§ 3.2), or sub-linearly with a fixed budget constraint (§ 4). In either case, the unit cost of our proposed processing is lightweight, costing as low as $0.01 per table even in large data lakes, when open-source models are used.

Figure 1b shows an example output, represented in a structured manner for navigation. Each row here represents a table, with basic table/column descriptions as well as statistical profiles shown in the second column “Basic info (B)”, that can be produced by prompting LLMs similar to prior work [53]. In addition, we represent the three example cross-table relationships $\mathcal{R} = \{\text{Confusable}, \text{Joinable}, \text{Union-able}\}$ as three additional columns to the right, with rich grounded context for why certain tables either differ or relate, which are made possible by today’s LLMs.

In addition to cross-table relationships, we also study table-to-code relationships, like illustrated in the last column of Figure 1b.

At online query time in Figure 1c, given a user task on the data lake — which can be data discovery, data analysis or data science — we show that suitably-designed agentic Data.Readme tools can enable LLMs to navigate a large collection of tables, by jumping from an initial candidate table, to additional tables that may be confusable/joinable/union-able as needed using the index and the tools we build, which we show is both much more effective (with higher task success rates), and efficient (with lower token usage and latency). We will explain the online step in § 3.3.

Offline Index: Extract Relationships

We now describe how we instantiate Data.Readme by extracting three example table relationships, $\mathcal{R} = \{\text{Confusable}, \text{Joinable}, \text{Union-able}\}$ in turn below, to populate the corresponding fields labeled as $C(T)/J(T)/U(T)$, for each $T \in\mathcal{L}$ in Figure 1b. These are on top of basic per-table descriptions “Basic info (B)”, denoted by $B(T)$, that contain table/column descriptions, primary-keys, grains, and statistical profiles that we obtain by prompting LLM once per-table using implementations similar to prior work [11, 53].

Confusable Tables. In a large data lake, it is not uncommon to have many similar-looking tables (e.g., 17 “Sales” tables like discussed in Example 1). Intuitively, we want our offline index to help LLMs understand how these tables differ, and which ones are really relevant to a task at hand, without needing to open up each and every Sales table to inspect at query time. This type of relationship has received little attention in the literature, but is now possible to study with modern LLMs.

The key challenge here lies in efficiently finding pairs of possibly confusable tables in a large lake $\mathcal{L}$. While files with the identical name are clearly confusable, it is unclear if other similarly-named tables are also confusable with a given target table (e.g., “Sales_latest” with “Sales”). Given the size of $\mathcal{L}$, we need to identify such potentially confusable tables efficiently without quadratic comparisons.

Algorithm 1: Query-driven discovery of confusable tables

input : Tables $\mathcal{L}$, basic description $\{B(T)\}_{T \in\mathcal{L}}$

output : Symmetric confusable group pairs $E$

1. $E \gets\varnothing$;

2. foreach $T \in\mathcal{L}$ do

3. $\quad Q_T \gets$ Generate $K$ LLM-brainstormed questions about $T$;

4. $\quad$ foreach $q \in Q_T$ do

5. $\qquad S_q \gets$ top $N$ tables retrieved for $q$ by embedding in $\{B(T)\}_{T \in\mathcal{L}}$;

6. $\qquad R_q \gets$ LLM ranked list of tables in $S_q$ for $q$;

7. $\qquad$ foreach $T'$ ranked higher than $T$ in $R_q$ do

8. $\qquad\quad E \gets E \cup\{(T,T'),(T',T)\}$

9. return $E$;

We develop a query-driven approach to identify such confusable tables, like shown in Algorithm 1. Specifically, for each target table $T$ that we want to find confusable tables for, we ask LLM to brainstorm a small number of $k$ (e.g., $k = 3$) questions that this $T$ can be used to answer (Line 3). For each such question $q$, we compare $q$’s embedding with the embedding of the basic descriptions of all tables $\{B(T)\}_{T \in\mathcal{L}}$, and retrieve the top-$N$ (e.g., $N = 20$) candidates denoted as $S_q$ (Line 5). We then ask an LLM to rank $S_q$ using a ranked list $R_q$, ordered from the most-likely to least-likely related to $q$, so that the LLM will likely open and inspect files in that order (Line 6). Since we know $T$ can be used to answer $q$ (as $q$ is a question brainstormed from $T$), we treat all tables that rank higher in $R_q$ than $T$ as potentially confusable with $T$. We repeat the process and return the set of confusable table pairs as $E$ (Line 9).

Such pairs can then be sent to LLMs, together with their basic descriptions $B(T)$, as well as profiling information (e.g., grains, primary-keys, value-ranges and statistical profiles for each column) collected while generating $B(T)$, to generate a description that can best distinguish this pair of confusable tables, like illustrated in the column “Confusable tables (C)” of Figure 1.

Example 2. We continue with Example 1 to show how confusable tables are generated. For each table $T$, we first ask LLM to brainstorm a small number of $k$ questions, $Q_T$, that can be answered by $T$. Suppose for the first table “Sales_1” in Figure 1, LLM generates a query $q \in Q_T$ as “store sales by country”. We embed $q$ and compare its embedding with the embeddings of basic description of all tables, $\{B(T)\}_{T \in\mathcal{L}}$, to retrieve the top-$N$ candidate tables with the highest embedding similarity to $q$, denoted by $S_q$ (which may include all 17 “sales” tables as well as others like “sales_latest”).

We then ask the LLM to rank $S_q$ based on their table descriptions and a sample of rows for each table in $S_q$. Suppose the LLM-ranked list is $R_q = \{\text{sales\_5}, \text{sales\_17}, \text{sales\_1}, \ldots\}$. We find that sales_5 and sales_17 are likely confusable with sales_1 for the LLM, since they rank higher than sales_1. To distinguish them, we ask the LLM to explain their differences. Perhaps sales_1 is for “global sales” while sales_5 is for “US sales”, and sales_1 is for “retail store sales” while sales_17 is for “stock sales”, etc., like shown in Figure 1b. □

Cost analysis. The per-table cost of annotating confusable tables for each target table $T$, denoted by $c(C)$, is at most $c(C) = (1 + kN)$ LLM calls, where both $k$ and $N$ are small constants. Here, 1 is for generating $k$ brain-stormed questions for $T$, and $kN$ is to explain all tables ranked higher than $T$ (which is at most $N$), for all $k$ questions. Note that in practice the number of LLM calls is much smaller, as LLM is often highly capable and can rank the target $T$ high in its ranked list – empirically, we find that on average LLM ranks only 1.7 tables above the target $T$ (or $N = 1.7$ empirically). Regardless, $c(C)$ scales only linearly in the size of the data lake $\mathcal{L}$ as both $k$ and $N$ are fixed constants.

Joinable Tables While join detection is a classical topic in data management as we will review in related work (§ 6), detecting joinable tables efficiently and accurately in large data lakes with tens of thousands of tables is still challenging.

Leveraging recent advances in both LLM and embeddings, we develop a scalable and accurate approach for joinable relationships in large data lakes, that adapts key ingredients from classical join detection [14, 36, 40, 55], as outlined in Algorithm 2.

[Key identification and enrichment]. In Line 3 of Algorithm 2, we start by using LLM to identify candidate primary-keys (PK) and foreign-keys (FK) in each table, using a single LLM call. Specifically, we provide LLM with each table’s schema and sample rows, together with statistical profiles in $B(T)$ (uniqueness, distinct values, etc.). Using statistical and semantic information, we ask LLMs not only to identify candidate PK/FK in each table (which they can predict very accurately), but also to enrich each PK/FK with alternative column names that are semantically meaningful.

Figure 2 shows such an example, where columns with blue boxes indicate LLM-predicted PK candidates, and columns with orange boxes indicate LLM-predicted FK candidates. LLM also enrich these PK/FK column names with alternative names, such as enriching the PK “id” column in “Sales_1” on the left, as “id” → “sales_id”, “transaction_id” etc., as well as enriching the PK candidate “c_id” in the two tables on the right, as “c_id” → “country_id”, etc.

[Embed PKs]. In Line 5 of Algorithm 2, we then embed each candidate PK column, using their original and alternative column-names, together with column-values, to produce $Emb(\mathcal{P})$. This is shown in the example of Figure 2 with the step marked as ①, where the PK column “c_id” for table “Country_5” is embedded using its original and enriched column names (“c_id”, “country_id”), as well as sample-values from the column (“1”, “2”, etc.).

[Embed FK for top-K]. Line 7 embeds each candidate FK column $f$ using the same column-names with sample-values to produce $Emb(f)$; in Line 8, we use $Emb(f)$ to retrieve top-$N$ $Emb(\mathcal{P})$, i.e., the PK columns with the highest similarity to the target $f$. The top-$N$ candidates are checked for PK/FK value containment, with passing pairs retained.

Using the example in Figure 2, with the “FK #2” in table “Sales_1” as the target FK $f$ like shown in step ②, we would embed its column names and values, to retrieve its embedding top-$K$ PK-candidates like shown in step ③, which include column “c_id” from table “Country_5” and “Country_9” shown on the right (note that these “c_id” columns are ranked high as embedding top-$K$ for $Emb(f)$, because both are enriched with meaningful column-names like “country_id”, thus producing good matches with $Emb(f)$). Both of these two “c_id” columns would be checked for PK/FK value containment checks and pass such checks.

[Semantic validation]. Finally, in Line 9, we perform an actual join using candidate PK/FK columns, and ask LLM to check samples from the joined row-pairs to validate semantic plausibility. For instance, in Figure 2, even though both “country_id” columns from “Country_5” and “Country_9” are retrieved as top-N, an LLM-validation step of the joined row-pairs would reveal the join with “Country_5” as invalid, because joining the country-names from “Country_5” into “Sales_1” shows semantic incompatibility (a US address like “Springfield, IL” in country “afghan”, which is thus pruned away; while the join with “Country_9” is semantically plausible and retained as a final PK candidate for “FK #2” (“country_id”) in the figure. All validated join relationships are then documented in Data.Readme like shown in column “Joinable tables (J)” of Figure 1.

Note that for each FK candidate, Algorithm 2 may return more than one PK candidate after all these steps, as in large data lakes PK/FK candidates may not be uniquely resolved. We do not force a unique PK/FK pairing in such cases, and use “late-binding” that retains all plausible pairs in DATA.README, and defer this to query-time for LLM to resolve (where a user query may contain additional disambiguating information, such as referencing a column that is only present in one of the candidate pairs).

Cost analysis. The per-table cost of extracting join-able relationships for each table $T \in\mathcal{L}$ using Algorithm 2, denoted by $c(J)$, is at most $c(J) = (1 + |F_T|)$ LLM calls, where 1 is for the LLM call to identify PK/FK candidates in $T$ (Line 3), and $|F_T|$ indicates the number of FK candidates on a table $T$, where the $|F_T|$ LLM calls are for validating and ranking the semantic-plausibility for each of the $|F_T|$ PK/FK candidates (Line 9). Since $|F_T|$ is the number of candidate FKs per table, it is usually a very small constant (empirically, less than 2 for data lakes we tested). The cost $c(J)$ is therefore a small constant, making its cost linear in the number of tables in $\mathcal{L}$.

Union-able Tables. Union-able tables are common in data lakes, and are often partitioned by time or geographic boundaries, because data pipelines would often dump data at regular intervals (e.g., daily or hourly), thereby creating sub-partitioned tables with identical schemas and similar filenames following a fixed pattern, like the examples from real data lakes in Figure 3 would show. This is widely reported in prior studies [6, 37, 43] and is very common in real data lakes, as such union-able tables are typically “machine-generated” by recurring pipelines [6, 37].

For this reason, we use a reference implementation to extract union-able tables, by clustering tables based on schema-names, and then present LLM with all tables in each cluster $C$ (with sample rows and statistical profiles in $B(T)$ for each table $T \in C$), so that LLM can determine which subsets are union-able and along which attribute, which are documented like shown in column “Union-able tables (U)” of Figure 1.

Note that while our reference implementation for union-able tables focuses on schema-aligned table partitions, other existing union-search methods [9, 20, 25, 28, 35] can be readily plugged into our framework through the same interface to enhance its coverage.

Cost analysis. Because each table $T \in\mathcal{L}$ can only fall into at most 1 cluster $C$, each table will be scanned at most once by the LLM for union-able relationships. The per-table cost for union-able relationships is therefore $c(U) = 1$, which also grows linearly as the lake $\mathcal{L}$ grows.

Online: Agentic Tools for Data.Readme

In a large data lake $\mathcal{L}$ with thousands or millions of tables, even succinct DATA.README documentation like in Figure 1 can be large (e.g., it can have millions of entries with one for each table), which would be expensive to load entirely into an LLM agent’s context window indiscriminately, as it degrades both the agent’s latency and quality (e.g., lost in the middle [33]). We therefore develop a set of agentic tools [38, 41] to work with DATA.README, like illustrated in Figure 1(c). Today’s LLMs are capable of invoking these tools appropriately, to selectively load only a relevant subset of DATA.README, and follow observed relationship-pointers to navigate across related tables on demand. We describe a few core tools below in turn:

Get_readme_by_RAG_top_k(query, start_pos, k). This “RAG-top-k” tool takes a user input query, and compares its embedding with the row-wise embedding of all table entries in DATA.README to retrieve the top-k most relevant to the user query. By default we set start_pos = 0, and $k = 50$ for agents to retrieve the first-50 matches, but the agent can always inspect the first-50 and if not finding relevant matches, retrieve the next $k$ by changing the start_pos parameter and invoke this tool again, which would retrieve the next batch of matches, etc.

Get_readme_by_table_names([table_list]). This “Retrieve-by-table-name” tool allows an agent to specifically retrieve a list of readme entries by name. It is useful because an agent may inspect an initial set of matches, find a relevant starting table $T$, and then decide that there is a need to jump to another relevant table $T'$ that may be confusable/joinable/union-able with $T$ for additional inspection (e.g., to see what $T'$ actually contains, and what other tables $T'$ can connect to). Invoking this tool allows LLMs to jump directly to these related tables by name.

Explore_table(table). This tool lets the agent actually open a table and explore data in a table, which agents can use for final verification or to resolve fine-grained details not present in DATA.README.

We also allow agents to use general python/sql tools, in addition to these readme-specific tools described above.

Example 3. We revisit Example 1 in Figure 1 to show how an agent may use these tools to navigate DATA.README. Suppose the input query is “global retail sales by customer country since 2024”, the agent first invokes Get_readme_by_RAG_top_k to retrieve the top-50 tables in readme that are the most similar to the query, which include many (but not all) Sales, Customer and Country tables in the lake. The agent inspects all returned tables’ readme entries, identifying Sales_1 as a possible candidate after reading fields such as “basic info (B)” and “confusable tables (C)” in the example.

From Sales_1, it may read its “joinable tables (J)” and “unionable tables (U)” fields and decide to navigate these connections, to Sales_14 (union-able with Sales_1 to answer the query), as well as Country_1 and Customer_9 (to join in order to answer the question). These additional tables may not be in the initial batch retrieved using RAG-top-k, in which case the agent can invoke Get_readme_by_table_names() to directly retrieve the readme for these tables using names.

Note that the “joinable tables (J)” field may contain more than 1 plausible join for an FK column, if semantic-validation (Line 9 of Algorithm 2) cannot uniquely identify one PK column to join with. In such cases readme has more than one join peers, which LLM can open and explore, to perform what we call a query-time “late-binding” to decide which plausible tables to actually bring in to answer user query. □

Data.Readme: Budget-Constrained Version

So far we studied how to extract relationships for all tables in a lake. We now consider the budget-constrained version in Definition 2.

Problem Formulation: BCTD

While our system described above can already process tables efficiently and in a cost-effective manner (costing as low as 1 cent per table), on really large lakes with millions of tables, and/or when a user has a fixed monetary budget $B$, we can instead focus on a subset of tables that is expected to be the most beneficial.

Because users are unlikely to hand-pick or manually specify what tables are useful to index, we rely on a “query log” $QL$, that can be a set of historical jobs/scripts/sql-queries representative of future queries, which are often available [10, 54] and are leveraged in prior studies [49, 50].

Intuitively, from the $QL$, we can extract what tables are being used and at what frequency, which is a proxy for how important each table $T$ is, and how beneficial it may be to index $T$. Let $QL = (Q_1, \ldots, Q_m)$ be the query log, we use $\mathcal{T}_i \subseteq\mathcal{L}$ to denote the set of tables used by each $Q_i$ (e.g., all tables accessed by this sql query or python script $Q_i$).

Given a monetary budget $B$ for indexing, and since Data.Readme is indexing tables at the table granularity (Figure 1), we reduce this to a table selection problem – namely, we want to select a subset of tables $D \subseteq\mathcal{L}$ for indexing, so as to maximize its possible benefit on $QL$.

On the cost side, for a selected table set $D$, since each table populates the same fields and follows the same steps in § 3.2, the offline cost of processing each table in $D$ is similar and can be pre-determined as a constant $\bar{k}$ (e.g., based on the average number of tokens consumed per table, and LLM token price). For a fixed budget $B$, this means that the number of tables we can select in $D$ cannot exceed $\lfloor B/\bar{k}\rfloor$, or $|D| \leq\lfloor B/\bar{k}\rfloor$.

On the utility side, for a selected table set $D$ that is indexed, the resulting readme is reliably beneficial for a query $Q_i \in QL$, only if all tables accessed in $Q_i$, written as $\mathcal{T}_i$, are contained in $D$ (as otherwise if a related table is missing from the readme, agents will likely have to fall back to brute-force exploration). We can therefore write the utility function as $F(D) = \sum_{i=1}^{m} \mathbb{1}\{\mathcal{T}_i \subseteq D\}$, where $\mathbb{1}\{\cdot\}$ is the indicator function, and $F(D)$ indicates how many queries in the query log $QL$ can be “covered” by our selected tables $D \in\mathcal{L}$.

We are now ready to reduce the high-level problem stated in Definition 2, to an exact optimization problem below that we term Budget-Constrained Table Documentation, defined below:

Definition 3. Budget-Constrained Table Documentation (BCTD). Given a data lake $\mathcal{L}$, a query log $QL = \{Q_1, \ldots, Q_m\}$, the set of tables used by each of the queries $\{\mathcal{T}_1, \ldots, \mathcal{T}_m\}$, a total budget $B$ and a per-table processing cost $\bar{k}$, select a subset of tables $D \subseteq\mathcal{L}$, such that:

We first establish that BCTD is equivalent to Densest $k$-Subhypergraph (DkSH) [15]. Using this equivalence, we develop a selection algorithm in the DkSH formulation and map its solution back to BCTD.

Lemma 1 (Equivalence to DkSH and Hardness). BCTD is polynomially equivalent to DkSH with repeated hyperedges counted by multiplicity. The reductions preserve the budget and objective, therefore BCTD is NP-hard.

Proof. To reduce BCTD to DkSH, create vertices $V = \{v_T : T \in\mathcal{L}\}$ and one hyperedge $e_i = \{v_T : T \in\mathcal{T}_i\}$ per logged query $Q_i$. For a table set $D$, let $X_D = \{v_T : T \in D\}$. Then

where $F_H$ counts contained hyperedges, including repetitions.

Conversely, reduce DkSH to BCTD by creating one table per vertex and one logged query per hyperedge occurrence. Every vertex set $X$ maps to $D_X = \{T : v_T \in X\}$ with $|D_X| = |X|$ and $F(D_X) = F_H(X)$. Both constructions are polynomial in the explicit query/hyperedge incidences and preserve the budget and objective. We use the at-most-$k$ form, which has the same optimum as selecting exactly $\min\{k, |V|\}$ vertices because $F_H$ is monotone.

Since ordinary DkSH is a special case and is NP-hard [7], BCTD is NP-hard. □

DensitySelect for BCTD

Based on Lemma 1, we use DkSH to develop an algorithm for BCTD. We first merge identical hyperedges and assign each its query multiplicity as a weight without changing $F_H$. We identify vertices with their tables and write $F$ for the common objective.

Selection algorithm. Because hyperedges can share vertices, selecting multiple hyperedges costs the size of their vertex union, not the sum of their individual sizes. We conservatively approximate this union cost with additive costs to obtain DensitySelect, an efficient density-based selection algorithm for BCTD.

We first discard queries touching more than $k$ tables and set aside empty-table queries, whose constant coverage is $w_0$. Merge identical hyperedges from the remaining queries into distinct nonempty hyperedges $A_1, \ldots, A_M$, with weight $w_j$ equal to the number of

Algorithm 3: DensitySelect: BCTD density-based selection
input : Candidate hyperedges $(A_j,w_j)_{j=1}^{M}$; vertex budget $k$
output : Selected vertices $D_{\mathrm{alg}}$
1 if $M=0$ then
2   return $\varnothing$;
3 Set $c_j \gets |A_j|$ and order hyperedges by nonincreasing $w_j/c_j$;
4 $D \gets \varnothing$; $b \gets 0$;
5 foreach $j$ in this order do
6   if $b+c_j\leq k$ then
7     $D \gets D\cup A_j$; $b\gets b+c_j$;
8 $j^\star \gets \arg\max_j w_j$;
9 return $\arg\max_{X\in\{D,A_{j^\star}\}}F(X)$;

queries represented by $A_j$. If $M=0$, the empty selection is optimal. Otherwise, define

Here $\Delta$ is the maximum number of candidate hyperedges incident to one vertex, and $\ell$ is the maximum hyperedge size.

In DensitySelect shown in Algorithm 3, we assign each hyperedge the additive cost $c_j=|A_j|$. We then sort hyperedges by nonincreasing $w_j/c_j$, admitting a hyperedge when the sum of admitted hyperedge costs remains at most $k$, and skipping it otherwise. It compares the resulting vertex union with the vertex set of the highest-weight individual hyperedge, returning whichever covers more queries. Density and single-hyperedge weight ties use hyperedge index; the packed selection wins a coverage tie.

We show that DensitySelect in Algorithm 3 has the following approximation guarantee.

Proof. The packed union contains at most $b\leq k$ vertices, and every candidate hyperedge has at most $k$ vertices. Thus either returned candidate is feasible.

Let $D^\star$ be an optimal vertex set and let $J^\star=\{j:A_j\subseteq D^\star\}$ index its covered hyperedges. Their additive cost satisfies

Taking a $1/\Delta$ fraction of each such hyperedge is therefore feasible for the fractional relaxation of the additive-cost problem over nonempty hyperedges with capacity $k$. If $V_{\mathrm{frac}}$ denotes its optimum, then

If no hyperedge is rejected, every candidate hyperedge is contained in the packed union, so the selection is optimal. Otherwise, let $r$ be the first rejected hyperedge and $P$ the total weight admitted before it. In density order, the fractional solution consists of this prefix and at most a fraction of $r$, so $V_{\mathrm{frac}}\leq P+w_r$. The completed packing has value at least $w_0+P$, while the highest-weight single-hyperedge candidate has value at least $w_0+w_r$. The better candidate therefore satisfies

Sorting takes $O(M\log M)$ time, while building the packed union and scoring the candidates takes $O(M\ell)$, thus showing the $O(M\log M+M\ell)$ running time.

Finally, we map the returned vertices to their corresponding tables. The equivalence preserves the table budget and query log coverage, so for $M>0$, Lemma 2 yields a feasible BCTD solution with at least a $1/(2\Delta)$ fraction of optimal coverage. Since $M\leq m$, its running time is also $O(m\log m+m\ell)$. Note that this algorithm uses only query-table incidence data and makes no LLM calls.

Experiments

We perform extensive evaluation to understand the effectiveness of Data.Readme on diverse tasks.

Data lakes. We create two experimental data lakes by pooling tables from public benchmarks BIRD [30], Spider [51], KramaBench [29] and BI-Bench [24]:

LakeOriginal: We pool all tables together from these 4 sources, and deduplicate at the table-level (as some public data sources are used by multiple benchmarks), which results in 4,127 tables. We refer to this as LakeOriginal.

LakeAugmented: To create an even larger and more challenging lake, we use LLM to synthesize group-by queries on randomly selected tables (to simulate user behaviors of performing aggregate analysis and then saving results [18]) to create 3,220 derived tables, and horizontally partitioned tables (to simulate partitioned-files that are common in data lakes [35, 43], e.g. in Figure 3) to create 5,482 tables. The resulting LakeAugmented contains 12,829 tables.

Table 1 summarizes the statistics of these lakes, and the offline construction costs to build Data.Readme on both lakes using all 6 backbone models tested. It can be seen that using open-source models like GPT-OSS-120B or DeepSeek-V4-Flash, the unit cost to process each table is as low as $0.01, making Data.Readme economically practical without any budget constraints.

Tasks. We evaluate 3 diverse data tasks using these data lakes:

Data discovery: In this task, an agent needs to identify tables in a lake relevant for a user query. We use queries in (BIRD, Spider, KramaBench, BI-Bench) as input, and measure exact-set match between the top-$K$ predicted tables and the ground-truth tables, where $K$ is the size of the ground-truth.

Data analysis: This task takes a user query and produces an answer using tables in a lake. We use queries in (BIRD, Spider, KramaBench, BI-Bench)¹, and report accuracy [29, 30] by comparing the predicted answer with ground-truth answers from these benchmarks.

Data science: Given a table $T$ and a target column $C\in T$, in this task an agent needs to build a predictive-model (regression for numerical targets and classification for categorical targets) to best predict the target column $C$. In a data lake setting, the agent can find additional external tables that may help improve prediction accuracy by joining or unioning into $T$. We evaluate using a set of 16 classification and 45 regression tasks², where we measure accuracy for classification tasks, and $R^2$ for regression tasks. We report gain recovery (GR), defined as GR = $\frac{\overline{\mathrm{gain}}_{\mathrm{method}}}{\overline{\mathrm{gain}}_{\mathrm{Gold}}} \times100\%$, which measures how much gain a method recovers on average ($\overline{\mathrm{gain}}_{\mathrm{method}}$) relative to the average gain of a Gold method ($\overline{\mathrm{gain}}_{\mathrm{Gold}}$) [13] that integrates all tables known to be related via joins/unions, followed by training using AutoGluon [19] to completion without a time limit.

Lake		Statistics				Construction cost (USD, per-table / total)
	Tables	Avg. rows	Avg. columns	Avg. cells	GPT-5.4	GPT-5.4-mini	GPT-5.4-nano	GPT-OSS-120B	DeepSeek-V4-Pro	DeepSeek-V4-Flash
LakeOriginal	4,127	97,359	14.71	554,125	0.299 / 1,235	0.090 / 371	0.024 / 101	0.017 / 71	0.061 / 253	0.015 / 63
LakeAugmented	12,829	47,490	10.99	294,848	0.222 / 2,854	0.067 / 857	0.018 / 233	0.013 / 162	0.045 / 580	0.011 / 145

Baselines. We compare 12 representative methods from 4 categories below. Because tasks above like data discovery and analysis are interactive in nature, we place a 4-turn limit where LLMs can interact with the environment at most 4 times, to make latency acceptable, which is fair across all methods (as otherwise we observe some baselines like coding-agents can spend over an hour working on a data lake). We additionally compare results with no such turn-limit in our sensitivity studies.

(1) Cross-table annotation. ① This is our proposed Data.Readme method. We report results using the variant that extract relationships in all tables (§ 3.2) by default, and study the variant with budget (§ 4) in § 5.2.

(2) Per-table annotation. ① AutoDDG [53] is a representative method in the per-table category, that prompts LLM to generate semantic descriptions per table, without cross-table relationships.

(3) Table retrieval methods. Since we are operating on a data lake for table tasks where retrieval of relevant tables is a key step, we compare with existing table-retrieval methods. We configure each retrieval method in two settings: (i) one-shot where we feed the original query $q$ into the retrieval system, and directly use the returned top-$K$ tables from each method for downstream tasks (data discovery/analysis/science); and (ii) agentic where we give an LLM full autonomy to rephrase query $q$ and invoke the retrieval system multiple times as needed, which is similar to the tool-use setting of Data.Readme.

This produces a total of 8 baselines: ② BM25 [39] and ③ BM25 (agentic) for lexical retrieval, ④ Hybrid (RRF) [16] and ⑤ Hybrid (RRF) (agentic) for lexical/vector rank fusion, ⑥ LlamaIndex [32] and ⑦ LlamaIndex (agentic) for table-vector retrieval, ⑧ Pneuma [8] and ⑨ Pneuma (agentic) for table summary retrieval.

(4) Coding agents. Modern coding agents such as Claude Code [2], Codex CLI [3], and GitHub Copilot CLI [4], are capable across a broad range of tasks, making them strong baselines for comparison. We use GitHub Copilot CLI as a representative frontier coding agent. We evaluate it using the same 4-turn limit as other methods, labeled as ⑩ Coding agent; as well as ⑪ Coding agent (unlimited), where we give the coding agent an unfair advantage with unlimited turns, and allow it to explore the lake for as much as it wants. This serves as a really strong reference point for quality comparisons.

Backbone models. We evaluate all methods with 6 different backbone models, for a total of $12 \times6 = 72$ model/method combinations. When a backbone is selected, it is used consistently across all steps in each method, including offline processing/indexing and online querying. The models we tested include 3 proprietary models ① GPT-5.4; ② GPT-5.4-mini and ③ GPT-5.4-nano; and 3 open-weight models ④ GPT-OSS-120B, ⑤ DeepSeek-v4 Pro, ⑥ DeepSeek-v4 Flash. We use default reasoning and temperature settings for all models.

Other setups. We use OpenAI’s text-embedding-3-large for text embeddings. Local data processing and evaluation run on an Ubuntu 24.04 server with 96 vCPUs (AMD EPYC 7452) and 661 GiB of RAM; LLM inference uses cloud-hosted APIs.

Main Results: Quality Comparisons

Data discovery. Table 2 shows a comparison of all methods on quality, across all models (6), benchmarks (4), and lakes (2) combinations, for a total of $6 \times4 \times2 = 48$ settings. Data.Readme outperforms all comparable baselines with the same turn-limit in 47 of 48 settings (with the remaining one being a tie). It significantly outperforms per-table annotation methods like AutoDDG, existing retrieval systems, and coding-agents.

Algorithm 2: Extract joinable relationships
input	: Tables in a lake $\mathcal{L}$
output	: Candidate joins $\mathcal{J}$
1	$\mathcal{P} \gets\emptyset$; $\mathcal{F} \gets\emptyset$; $\mathcal{J} \gets\emptyset$;
2	foreach $T \in\mathcal{L}$ do
3	$(P_T, F_T) \gets$ LLM-inferred PK/FK on $T$ using $B(T)$;
4	$\mathcal{P} \gets\mathcal{P} \cup P_T$; $\mathcal{F} \gets\mathcal{F} \cup F_T$;
5	$Emb(\mathcal{P}) \gets$ Embed $\mathcal{P}$ by (column names + sample values);
6	foreach $f \in\mathcal{F}$ do
7	$Emb(f) \gets$ Embed $f$ by (column names + sample vals);
8	$C_f \gets$ Retrieve top-$N$ PK in $Emb(\mathcal{P})$ using $Emb(f)$, that pass PK/FK containment checks;
9	$P_f \gets$ LLM validates joined-sample, ranks semantically plausible top-$k$;
10	$\mathcal{J} \gets\mathcal{J} \cup\{(f,p): p \in P_f\}$;
11	return $\mathcal{J}$;

LakeAugmented is clearly more challenging, where all methods have lower scores. Data.Readme continues to show a substantial lead over all methods on this lake. Even against the “Coding agent (unlimited)” reference point (which enjoys an advantage of having unlimited LLM turns), Data.Readme achieves higher accuracy in 13 of the 16 settings.

Data analysis. Table 3 shows a similar comparison for data analysis, where Data.Readme achieves the highest score in 45 of 48 settings. As with data discovery, Data.Readme generally outperforms the strong Coding agent (unlimited). It is encouraging to see that Data.Readme using smaller backbones can often outperform baselines using stronger and more expensive backbones. We also note that on the challenging LakeAugmented, the lead of Data.Readme often widens compared to LakeOriginal.

Table 3: Data analysis scores (%). Each cell: LakeOriginal / LakeAugmented. For Coding agent, –/– denotes unavailable results because the corresponding model is not offered in Coding agent as a model option.

model

Data.Readme

AutoDDG

Pneuma

Pneuma (agentic)

BM25

BM25 (agentic)

Hybrid (RRF)

Hybrid (RRF) (agentic)

LlamaIndex

LlamaIndex (agentic)

Coding agent (Copilot CLI)

Coding agent (Copilot CLI, unlimited)

bird-paraphrase (NL2SQL)

gpt-5.4

43.3/43.8

36.7/31.1

19.7/13.2

30.2/22.1

16.0/10.7

26.9/22.1

26.1/19.5

36.2/26.6

23.6/15.7

34.0/25.8

4.8/5.3

28.9/26.9

gpt-5.4-mini

32.1/32.4

28.9/22.5

16.7/11.2

21.5/14.7

12.9/8.6

19.5/12.1

20.7/15.0

26.3/19.7

17.0/13.9

24.6/15.9

4.5/5.3

23.5/19.0

gpt-5.4-nano

31.4/29.6

26.0/19.2

10.9/8.4

14.5/9.4

11.7/7.9

15.4/10.9

16.2/12.2

22.8/16.9

16.0/12.1

21.8/15.5

–/–

–/–

gpt-oss-120b_1

24.0/19.3

9.1/8.3

12.4/8.4

12.9/9.4

11.4/7.3

14.0/10.7

16.7/12.2

19.3/13.6

15.7/11.9

17.9/11.6

–/–

–/–

deepseek-v4-pro

37.9/39.0

28.9/23.6

8.6/7.1

20.0/14.4

9.1/6.1

19.7/11.7

11.9/10.1

25.6/21.0

10.7/8.8

24.8/17.4

–/–

–/–

deepseek-v4-flash

33.6/32.6

26.6/19.7

7.3/6.0

15.5/9.4

8.6/5.8

15.9/9.8

12.1/8.6

25.6/17.9

8.8/7.8

22.6/17.4

–/–

–/–

spider-paraphrase (NL2SQL)

gpt-5.4

64.6/64.6

57.3/52.2

38.3/33.6

51.1/41.2

10.9/6.6

28.8/21.2

52.9/46.0

56.2/51.1

52.9/47.4

59.9/54.4

6.2/4.4

43.1/41.6

gpt-5.4-mini

57.3/57.3

47.8/47.4

36.9/30.7

42.3/33.9

10.2/6.2

22.3/11.7

44.5/40.5

49.6/46.0

45.6/40.1

52.2/49.3

5.1/4.0

33.9/30.7

gpt-5.4-nano

52.2/51.1

45.3/38.0

31.4/26.3

35.4/28.8

9.5/4.7

17.2/9.9

36.5/33.6

46.0/39.1

40.1/37.6

46.4/43.8

–/–

–/–

gpt-oss-120b_1

44.5/40.1

29.2/28.1

33.9/25.5

37.6/29.6

8.4/5.8

18.2/9.5

39.8/33.9

36.9/35.4

40.9/36.5

41.2/36.9

–/–

–/–

deepseek-v4-pro

52.9/54.7

48.2/45.3

25.2/21.2

34.7/29.2

7.7/4.7

19.3/10.9

23.0/23.4

48.9/44.5

29.9/28.5

52.2/45.6

–/–

–/–

deepseek-v4-flash

56.2/50.4

46.7/44.5

21.9/16.8

35.0/24.8

5.1/4.4

9.1/5.1

19.0/20.4

45.6/41.2

22.3/23.7

46.4/40.9

–/–

–/–

bibench (NL2SQL)

gpt-5.4

63.0/63.0

50.0/37.0

40.7/24.1

46.3/27.8

18.5/13.0

40.7/27.8

38.9/24.1

51.9/42.6

33.3/24.1

46.3/35.2

7.4/3.7

51.9/57.4

gpt-5.4-mini

51.9/51.9

38.9/22.2

29.6/20.4

29.6/24.1

20.4/11.1

37.0/22.2

31.5/20.4

40.7/29.6

40.7/14.8

42.6/24.1

1.9/1.9

42.6/40.7

gpt-5.4-nano

44.4/35.2

35.2/29.6

22.2/13.0

27.8/14.8

16.7/9.3

35.2/20.4

31.5/16.7

25.9/20.4

31.5/14.8

27.8/22.2

–/–

–/–

gpt-oss-120b_1

44.4/40.7

9.3/9.3

25.9/13.0

22.2/7.4

16.7/7.4

31.5/16.7

29.6/22.2

29.6/24.1

33.3/16.7

25.9/20.4

–/–

–/–

deepseek-v4-pro

57.4/55.6

38.9/29.6

13.0/0.0

31.5/13.0

11.1/5.6

31.5/13.0

16.7/9.3

35.2/27.8

22.2/9.3

40.7/27.8

–/–

–/–

deepseek-v4-flash

50.0/50.0

42.6/18.5

7.4/1.9

27.8/14.8

11.1/9.3

22.2/14.8

13.0/7.4

38.9/27.8

11.1/5.6

37.0/25.9

–/–

–/–

kramabench-paraphrase (NL2Python)

gpt-5.4

58.4/59.6

56.5/59.2

42.2/39.3

53.5/44.8

21.8/17.6

54.2/42.0

51.8/52.7

57.4/57.9

45.7/47.7

58.7/57.9

21.0/13.3

64.5/58.3

gpt-5.4-mini

52.2/51.9

36.8/41.6

17.7/18.6

38.8/33.4

8.9/4.5

35.0/16.1

25.8/31.5

39.8/35.9

27.7/26.4

43.4/44.9

14.9/12.9

61.1/50.7

gpt-5.4-nano

38.2/38.3

28.2/25.9

21.4/13.6

32.7/25.5

10.5/6.4

26.3/17.6

28.1/21.2

32.2/33.0

21.4/23.0

34.6/28.9

–/–

–/–

gpt-oss-120b_1

35.6/30.8

16.0/7.1

18.3/13.8

24.1/15.0

9.0/10.7

15.2/13.7

22.3/24.8

25.2/22.7

21.4/19.1

29.0/26.9

–/–

–/–

deepseek-v4-pro

39.7/41.5

37.4/39.0

12.5/11.2

32.5/35.3

7.1/7.4

17.7/11.5

18.4/16.6

41.3/33.6

23.7/22.2

35.5/35.7

–/–

–/–

deepseek-v4-flash

39.3/41.3

31.5/21.5

15.4/19.1

26.3/22.8

7.4/3.1

22.6/4.9

13.5/14.7

40.2/33.4

14.0/14.0

28.8/31.6

–/–

–/–

Data science. Figure 4 shows the quality comparison on data science tasks, where Data.Readme helps agents perform better on predictive modeling by leveraging related tables – it recovers 71.96% of gold model’s gains on classification, and 84.17% on regression. We additionally tested a method labeled as “Coding agent + Data.Readme”, shown as the rightmost method in the figure, where we provide our produced Data.Readme as an additional resource for the coding-agent. Compared to “Coding agent” without readme shown to its left, this readme-augmented coding-agent achieves substantial quality improvements – its gain recovery increases from 24.80% to 98.47% on classification and from 77.62% to 99.82% on regression, again showing the benefit of our using readme.

model

Data.Readme

AutoDDG

Pneuma

Pneuma (agentic)

BM25

BM25 (agentic)

Hybrid (RRF)

Hybrid (RRF) (agentic)

LlamaIndex

LlamaIndex (agentic)

Coding agent (Copilot CLI)

Coding agent (Copilot CLI, unlimited)

bird-paraphrase

gpt-5.4

74.7/51.7

64.5/37.6

4.1/0.2

50.9/26.4

2.3/0.8

44.7/28.4

13.6/4.4

60.1/39.1

12.5/1.6

58.1/34.3

14.8/7.4

72.6/53.0

gpt-5.4-mini

57.0/37.4

49.6/20.9

5.7/0.7

39.6/20.5

2.3/0.8

30.5/15.1

13.6/4.4

45.0/26.1

12.5/1.6

44.0/25.5

8.7/4.4

50.1/31.4

gpt-5.4-nano

57.3/35.8

48.3/18.2

4.4/0.3

34.3/14.8

2.3/0.8

27.8/12.2

13.6/4.4

41.4/23.8

12.5/1.6

39.7/23.8

–/–

–/–

gpt-oss-120b_1

41.7/21.7

35.6/15.3

4.4/0.3

24.0/8.0

2.3/0.8

23.3/11.2

13.6/4.4

39.2/21.7

12.5/1.6

36.8/21.0

–/–

–/–

deepseek-v4-pro

66.8/46.3

51.2/25.1

4.4/0.3

36.9/13.3

2.3/0.8

31.4/19.7

13.6/4.4

46.1/27.1

12.5/1.6

47.5/25.3

–/–

–/–

deepseek-v4-flash

60.8/37.9

49.3/21.8

3.0/0.0

25.8/9.2

2.3/0.8

23.5/9.9

13.6/4.4

45.2/24.0

12.5/1.6

46.0/22.7

–/–

–/–

spider-paraphrase

gpt-5.4

75.2/66.1

65.3/51.8

10.9/7.7

61.7/43.1

0.0/0.0

31.4/25.2

18.2/12.4

66.1/55.8

37.2/18.2

69.0/53.3

25.9/12.4

69.3/65.7

gpt-5.4-mini

64.6/56.6

58.4/41.2

11.3/6.9

58.4/36.9

0.0/0.0

23.7/10.9

18.2/12.4

60.9/47.4

37.2/18.2

59.9/46.4

16.8/12.4

51.1/41.2

gpt-5.4-nano

66.1/55.1

54.4/33.6

13.1/8.4

51.5/33.9

0.0/0.0

22.6/10.2

18.2/12.4

55.8/43.4

37.2/18.2

54.7/42.3

–/–

–/–

gpt-oss-120b_1

58.0/42.7

48.5/28.1

13.1/6.6

43.4/29.2

0.0/0.0

21.5/11.3

18.2/12.4

48.5/38.7

37.2/18.2

55.5/41.2

–/–

–/–

deepseek-v4-pro

69.0/62.0

55.8/40.9

12.0/6.6

51.8/33.2

0.0/0.0

26.3/18.6

18.2/12.4

57.3/47.8

37.2/18.2

61.3/51.1

–/–

–/–

deepseek-v4-flash

64.6/55.8

56.9/45.6

11.7/6.2

43.8/26.6

0.0/0.0

14.2/6.9

18.2/12.4

55.5/50.0

37.2/18.2

60.2/49.3

–/–

–/–

bibench

gpt-5.4

68.5/57.4

53.7/27.8

13.0/0.0

55.6/35.2

1.9/0.0

46.3/27.8

20.4/0.0

50.0/38.9

13.0/0.0

44.4/38.9

29.6/25.9

64.8/51.9

gpt-5.4-mini

51.9/42.6

42.6/25.9

13.0/1.9

42.6/29.6

1.9/0.0

42.6/18.5

20.4/0.0

48.1/31.5

13.0/0.0

44.4/31.5

18.5/9.3

55.6/37.0

gpt-5.4-nano

61.1/40.7

40.7/20.4

13.0/0.0

42.6/24.1

1.9/0.0

37.0/22.2

20.4/0.0

40.7/29.6

13.0/0.0

42.6/27.8

–/–

–/–

gpt-oss-120b_1

59.3/46.3

27.8/14.8

16.7/0.0

48.1/16.7

1.9/0.0

40.7/22.2

20.4/0.0

44.4/29.6

13.0/0.0

37.0/24.1

–/–

–/–

deepseek-v4-pro

59.3/50.0

40.7/27.8

11.1/0.0

51.9/22.2

1.9/0.0

44.4/22.2

20.4/0.0

55.6/35.2

13.0/0.0

44.4/27.8

–/–

–/–

deepseek-v4-flash

59.3/50.0

44.4/18.5

11.1/0.0

40.7/18.5

1.9/0.0

48.1/11.1

20.4/0.0

51.9/33.3

13.0/0.0

48.1/31.5

–/–

–/–

krambench-paraphrase

gpt-5.4

63.5/67.1

62.4/64.7

7.1/5.9

50.6/41.2

0.0/0.0

41.2/22.4

16.5/12.9

61.2/57.6

18.8/17.6

60.0/60.0

35.3/23.5

65.9/63.5

gpt-5.4-mini

60.0/61.2

55.3/51.8

3.5/5.9

44.7/29.4

0.0/0.0

32.9/17.6

16.5/12.9

50.6/51.8

18.8/17.6

52.9/51.8

24.7/20.0

57.6/50.6

gpt-5.4-nano

64.7/60.0

54.1/49.4

8.2/9.4

49.4/40.0

0.0/0.0

38.8/20.0

16.5/12.9

60.0/51.8

18.8/17.6

54.1/48.2

–/–

–/–

gpt-oss-120b_1

55.3/51.8

48.2/40.0

9.4/4.7

28.2/24.7

0.0/0.0

30.6/20.0

16.5/12.9

54.1/47.1

18.8/17.6

49.4/45.9

–/–

–/–

deepseek-v4-pro

69.4/61.2

58.8/54.1

8.2/8.2

44.7/34.1

0.0/0.0

28.2/11.8

16.5/12.9

56.5/50.6

18.8/17.6

61.2/54.1

–/–

–/–

deepseek-v4-flash

61.2/63.5

52.9/47.1

10.6/7.1

32.9/28.2

0.0/0.0

16.5/4.7

16.5/12.9

57.6/49.4

18.8/17.6

55.3/54.1

–/–

–/–

Main Results: with Budget-Constraints

Figure 5 evaluates our proposed method, DensitySelect (Algorithm 3), for the budget constraint problem variant³, across different budget levels, with the table budget $k = \frac{B}{\bar{b}} \in\{10, 50, 100, 150, 175, 200, 250\}$. We compare results from constrained configurations, against the full unconstrained version ($All$).

Discovery quality in end-to-end tasks. Figure 5(a) shows that we selectively process tables while retaining near-full discovery quality with substantially lower construction cost. At $k = 175$, documenting 126 BIRD tables yields a 76.01% weighted Exact score, only losing 1.94% from All; whereas construction cost falls from $104.20$ to $22.17$. On Spider, 172 tables yield 84.08% versus 86.76%, a loss of 2.68 points, with cost falling from $141.23$ to $26.64, showing that

DensitySelect can indeed substantially reduce cost while maintaining quality.

Solution quality using the objective function. Figure 5(b) shows that DensitySelect can achieve near-optimal selection utility as defined in Equation (1). The dotted line is the true optimal utility (from brute-force enumeration), and the solid line is the utility of the solution produced by our algorithm, where our solution is close to theoretical optimum, showing the effectiveness of our approximation algorithm when measured by the raw objective function.

Solution scalability. Figure 5(c) shows that our algorithm runs efficiently and can scale to large query workloads as the query size grows – With $k = 200$, median selection latency at $m = 10000$ is 12.50 ms on BIRD and 10.34 ms on Spider. The trend with $m$ is consistent with the $O(m \log m + m\ell)$ complexity discussed in Section 4.2.

Ablation Study

Coding Agent Ablation: with/without Readme. Given the strength and generality of today’s coding agents, we perform an additional test where we provide our produced Data.Readme to coding agent as an additional resource, and test its quality/latency comparisons with vs. without Readme, across different LLM-turn budget settings (1/4/8/16/unlimited).

Answer quality. Figure 6 shows that merely providing readme to a coding agent improves its answer quality at every tested budget setting across all four workloads. With 8 turns, Coding agent with readme improves its counterpart without readme significantly by 16 to 30 percentage points, even when both variants have unlimited turns, the one with readme still retains sizable benefits.

Query latency. Importantly, the quality gains of readme are accompanied by higher-efficiency / reduced-latency in every setting, as readme allows the agent to perform tasks much more efficiently. With unlimited calls, the mean latency of using readme improve by up to 6x times, which represent significantly lower user wait time and better user experience.

Ablation of different relationships. In Figure 7, we evaluate how each relationship type extracted contributes to downstream task quality. Starting from Auto-DDG-like per-table table descriptions and profiles (referred to as Base), we add confusable tables (+C), joinable tables (+J), union-able tables (+U), as well as everything combined (+UCJ) and compare their quality results on benchmark queries involving multiple tables.

The full method (+UCJ) achieves the best on all four workloads across tasks. The strongest individual component varies: +J leads on the SQL workloads, while +U leads or ties on KramaBench, which are dependent on the characteristics of the underlying workload.

Sensitivity and Efficiency

Sensitivity to embedding models. We replace the default embedding model, OpenAI’s text-embedding-3-large, with three lightweight embedding models that can run locally on CPUs: MiniLM-L6 [46], BGE-small [47], and E5-small [45]. Table 4 shows a comparison on discovery and analysis quality using LakeAugmented. With lightweight embedding models, Data.Readme performance drops by 2-4 percentage points, but is still significantly better than the best baseline, Hybrid RRF, on both tasks, illustrating that our quality gains are not dependent on big embedding models.

Method	Discovery (%)	Analysis (%)
Data.Readme + text-embedding-3-large	60.56	57.74
Data.Readme + all-MiniLM-L6-v2	56.65	53.37
Data.Readme + bge-small-en-v1.5	58.58	54.56
Data.Readme + e5-small-v2	58.55	54.14
Best baseline - Hybrid RRF agentic	47.86	44.55

Construction Efficiency and Sensitivity. We measure offline construction cost/latency as the number and size of tables increase. To vary table count, we perform constructions on sampled subsets with 200, 400, 800, and 1,600 tables from LakeOriginal. Figure 8(a) reports elapsed construction time and LLM cost as we increase the number of tables, which grows linearly with the number of tables. We also vary the table size (the number of rows in a table), by selecting 100 tables from the lake each with at least 100K rows, and then down-sample each to 100, 1K, 10K, and 100K rows, respectively, and perform construction experiments. Figure 8(b) shows that LLM cost and latency are not sensitive to row count: increasing row count from 100 to 100K raises cost and latency only slightly, which shows the scalability of our approach to large tables and large lakes.

Incorporating code-to-table relationships

Historical SQL queries complement table metadata by providing examples of how tables are used [22], and can be attached to each table using the last column shown in Figure 1. We evaluate whether Data.Readme benefits from this additional context on BIRD and Spider in LakeAugmented. We use 80% of the queries to construct a historical query log $Q_L$ and reserve the remaining 20% for evaluation. To integrate the knowledge of $Q_L$, We store each SQL in $Q_L$ in the snippet field of the Data.Readme entry for every table it references. These examples are then available alongside retrieved Data.Readme.

Figure 9 shows that query history improves both Discovery Exact and SQL execution accuracy on BIRD and Spider. On BIRD, the gains are 5.79 and 4.13 percentage points, respectively. These gains suggest that historical queries provide useful context.

Related work

Dataset annotation using LLMs. In addition to earlier work that uses traditional methods to expand the semantics of tables and columns [17, 26, 42, 48, 52], recent work such as AutoDDG [53] and TACO [11] use LLMs to generate dataset and column descriptions based on table content. Data.Readme addresses a different limitation: independently annotating each table does not explain relationships between tables. We therefore augment per-table descriptions with structured, lake-wide relationships and develop tools that let agents retrieve and traverse them, which are shown to improves the quality and efficiency of downstream data tasks.

Join discovery and search. There is a large literature on join discovery that aims to identify all joins from a set of tables, where most prior work focus on join discovery in smaller-scale, database settings, often with tens of tables [14, 36, 40, 55]. Scalable joinable-table search has also been studied using efficient value-overlap methods [57], where the goal is to find joinable tables for one target table. There is limited study thus far on scaling all-pair join discovery to large data lakes with tens of thousands of tables, while efficiently producing semantically plausible join relationships. Our setting additionally requires identifying and documenting semantically plausible PK/FK relationships across the lake, where value overlap alone may produce spurious connections.

Table union search. There is a long and fruitful line of research on table union search [9, 20, 25, 28, 35], which retrieves tables whose columns are semantically compatible to one target search table. While we use schema-aligned table partitions as a reference implementation for union-able relationships in this work, our focus is on documenting these relationships for downstream agents; alternative union-search methods could be easily plugged into Data.Readme using the same relationship interface.

Relationship-based data discovery. Systems like Aurum [21] construct and maintain a lake-wide graph of schema similarity, content similarity, and key relationships. Data.Readme shares the principle of precomputing lake-wide knowledge, but focuses on developing an explanatory documentation framework specifically designed for LLM agents, with new relationships such as confusable relationships, and extensible to new relationship types.

Conclusions and Future Work

We presented Data.Readme, structured documentation that helps LLM agents navigate large data lakes using offline relationship extraction. Our experiments show the promise of Data.Readme as reusable, relationship-aware documentation that can serve as an effective interface between data lakes and LLM agents.

References