Shadow Ingest Quick Start¶

This page answers one practical question:

As a new user, how do I pull data as quickly as possible?

Install¶

uv pip install git+ssh://git@github.com/Fund-Sapiens/shadow-ingest.git

If you are developing from the repository itself:

uv pip install -e .

Choose Your Access Mode¶

Remote client mode¶

This is the standard and recommended setup for most users.

export SHADOW_INGEST_REMOTE_URL=http://YOUR_SERVER_HOST:30110
export SHADOW_INGEST_FLIGHT_URL=grpc://YOUR_SERVER_HOST:30100

In this mode, the SDK chooses the transport automatically and still returns a normal polars.DataFrame.

Local parquet mode¶

Use this only when your machine can read the parquet tree directly.

export SHADOW_INGEST_DATA_ROOT=/path/to/data

Fastest Safe First Query¶

If you do not yet know the valid dates, codes, or fields, start with the helper APIs.

import shadow_ingest as si

price_fields = si.list_fields(si.gather_daily_price)
trade_dates = si.list_market_calendar(year=2024)
stock_codes = si.list_universe(date=trade_dates[-1])

print(price_fields[:5])
print(trade_dates[-3:])
print(stock_codes[:5])

Then run the actual data query:

import shadow_ingest as si

price_df = si.gather_daily_price(
    stock_codes=['000001.XSHE'],
    start_date='2024-01-02',
    end_date='2024-01-03',
    fields=['open', 'close', 'volume'],
)

print(price_df)

Pandas Users¶

The SDK returns polars.DataFrame by default.

If you prefer pandas, convert after fetching:

price_pdf = price_df.to_pandas()

Read Next¶

• API Overview
• gather_daily_price
• list_fields
• list_market_calendar
• list_universe

Common Configuration Error¶

If you see:

ValueError: data_root is required. Pass it explicitly or set SHADOW_INGEST_DATA_ROOT.

then the client detected neither:

• a configured remote endpoint
• nor a local parquet root

For most normal users, the correct fix is to configure the remote endpoints.