Bug Hunting with XBRL Query

The primary use case for XBRL in edgartools is to get and view financial statements. Another powerful feature is querying XBRL data to selectively build your own datasets from the facts in the XBRL. So if you wanted to find the facts containing the phrase 'Revenue' then the query functionality is what you need.

I originally added the query API to allow tracing issues when generating financial statements. Generating statements follow a complex code path, and being able to query from what you could see e.g. Revenue $245,000,000 back to the original data was very helpful. Now I use it pretty regularly when fixing XBRL issues and my workflow for most issues involving XBRL involves locating the company, getting the XBRL object then writing XBRL query code.

As an example I will write the following query to find facts where the label is "Total deferred revenue".

c = Company("AAPL")
f = c.latest("10-K")
xb = f.xbrl()

xb.query().by_label("Total deferred revenue")

Or I can query by the concept "us-gaap:ContractWithCustomerLiability". The benefit is that I can see what the raw value is and compare against the user's expectation.

Bug Hunting

Now let's go bug hunting. In Github Issue 322 there was some data missing in the Income Statement. My code to debug is as follows

from edgar import *
from edgar.xbrl import *

c = Company('XOM')
filings = c.get_filings(form="10-K").latest(4)
xbs = XBRLS.from_filings(filings)
income_statement = xbs.statements.income_statement()
print(income_statement)

I notice that the earnings per share are all 0.00. The query to see the underlying values would be

results = xbs.query().by_label("Earnings Per Share")
print(results.to_dataframe('concept', 'label', 'value', 'period_start', 'period_end'))

This shows that the underlying values for earnings per share are present in the raw XBRL data. I think it has to do with the formatting of the per share amounts, since these need to be simple dollars and cents rather than millions or billions. So I described the bug to Claude Code and it one-shotted a fix, including writing and fixing new tests

Now we can see the per share values

Conclusion

This is a peek inside how I find and resolve bugs in edgartools. It also shows how you can use the XBRL query functionality for your own uses.

edgartools is the easiest way to work with SEC filings in Python. You can install it with pip or uv and give it a star on Github.