Request options

Overrides, elements, types, and sharding.

Everything you can attach to a request beyond securities and fields — and how xbbg routes each option to Bloomberg.

Keyword arguments: overrides or request elements

Extra keyword arguments on the request helpers are routed by name:

• Request elements — names in the operation's Bloomberg schema (for example periodicitySelection, maxDataPoints, adjustmentSplit) and the Excel-style aliases below — become request elements.
• Field overrides — UPPERCASE names or Mixed_Case names with an underscore (for example EQY_FUND_CRNCY, VWAP_Dt) — become Bloomberg overrides.
• Anything else is sent as a request element for Bloomberg to validate, with a warning when the operation's schema is known.

from datetime import date

from xbbg import blp

# Override: VWAP for a given date
vwap = blp.bdp('AAPL US Equity', 'Eqy_Weighted_Avg_Px', VWAP_Dt='20240115')

# Date values in overrides are normalized to YYYYMMDD
px = blp.bdp('AAPL US Equity', 'PX_LAST', USER_LOCAL_TRADE_DATE=date(2023, 1, 17))

# Request element (schema name)
weekly = blp.bdh('SPX Index', 'PX_LAST', '2024-01-01', '2024-06-30', periodicitySelection='WEEKLY')

Override values that are datetime.date, datetime.datetime, duck-typed pandas.Timestamp, or ISO/YYYYMMDD strings are sent as YYYYMMDD; booleans are sent as 'True'/'False'.

Composable overrides with ovr()

overrides= accepts a mapping, a sequence of (name, value) pairs, or an OverrideSpec built with xbbg.ovr(). Specs are immutable and compose:

from xbbg import blp, ovr

eur = ovr(EQY_FUND_CRNCY='EUR')
adj = blp.bdp('AAPL US Equity', 'CRNCY_ADJ_PX_LAST', overrides=eur)

# Merge specs; later values win
both = eur | ovr({'BEST_FPERIOD_OVERRIDE': '1BF'})
print(both.to_dict())

OverrideSpec behaves like a read-only mapping and offers to_pairs(), to_dict(), to_security_pairs(), and for_security().

Per-security overrides

Nest an ovr() (or mapping) under a security inside ovr() to give that security its own overrides. Global pairs are applied first; a security's own pairs win for the same name.

from xbbg import blp, ovr

per_sec = blp.bdp(
    ['AAPL US Equity', 'MSFT US Equity', 'IBM US Equity'],
    'CRNCY_ADJ_PX_LAST',
    overrides=ovr(
        {
            'EQY_FUND_CRNCY': 'USD',                          # everyone
            'AAPL US Equity': ovr(EQY_FUND_CRNCY='EUR'),      # AAPL only
            'MSFT US Equity': ovr(EQY_FUND_CRNCY='JPY'),      # MSFT only
        }
    ),
)

# Equivalent builder form
spec = ovr(EQY_FUND_CRNCY='USD').for_security('AAPL US Equity', EQY_FUND_CRNCY='EUR')

Per-security overrides are supported by bdp(), bdh(), and bds() (and their async variants); other helpers raise TypeError. The engine splits the request into runs of adjacent securities that share the same overrides and returns rows in the original order.

Excel-style request aliases

bdh(), bdib(), and bdtick() accept the request aliases from the Bloomberg Excel add-in and xbbg 0.x. They become Bloomberg request elements, and shorthand values are expanded.

Alias	Bloomberg element	Shorthand values
Per, Period	periodicitySelection	D, W, M, Q, S, Y → DAILY … YEARLY
PerAdj, PeriodAdj	periodicityAdjustment	A actual, C calendar, F fiscal
Days	nonTradingDayFillOption	W/N/Weekdays, C/A/All, T/Trading
Fill	nonTradingDayFillMethod	P/C/Previous → previous value, B/Blank/NA → nil
Points	maxDataPoints	integer
Curr, Currency, FX	currency	ISO code
Quote	overrideOption	A/G/Average, C/Close
QuoteType, QtTyp	pricingOption	P/Price, Y/Yield
CshAdjNormal, CshAdjAbnormal, CapChg, UseDPDF	adjustmentNormal, adjustmentAbnormal, adjustmentSplit, adjustmentFollowDPDF	booleans
Calendar	calendarCodeOverride	calendar code
BarSz, BarSize	interval	minutes
BarTp, BarType	eventType	T/Trade, B/Bid, A/Ask
IncludeExchangeCodes	includeExchangeCodes	boolean

from xbbg import blp

monthly = blp.bdh(
    'AAPL US Equity',
    'PX_LAST',
    start_date='2023-01-01',
    end_date='2024-01-01',
    Per='M',      # periodicitySelection='MONTHLY'
    Fill='P',     # nonTradingDayFillMethod='PREVIOUS_VALUE'
    Points=12,    # maxDataPoints=12
    CapChg=True,  # adjustmentSplit=True
)

The Excel presentation aliases (Dts, DtFmt, Sort, Direction) shape bdh() output locally instead; see Output Formats.

bdh() also takes adjust= as a shortcut for corporate-action adjustments: 'all' sets split, normal, and abnormal adjustments; 'dvd' sets normal and abnormal (dividend) adjustments; 'split' sets split adjustment only. If start_date is omitted, bdh() starts eight weeks before end_date (default 'today').

Field types

field_types (on bdp, bdh, and request) fixes a field's output type, overriding the field type cache:

from xbbg import blp

df = blp.bdp(
    'AAPL US Equity',
    ['PX_LAST', 'VOLUME', 'DVD_EX_DT'],
    format='long_typed',
    field_types={'VOLUME': 'int64', 'DVD_EX_DT': 'date32'},
)

Accepted type names are float64, int64, int32, string, bool, date32, timestamp, and time64, plus the aliases listed in Type Mappings. An unknown name raises BlpValidationError before anything is sent to Bloomberg.

Field validation

Field validation checks reference and historical requests (bdp, bds, bdh) against Bloomberg's field dictionary before sending them.

Setting	Effect
validate_fields=True	Unknown fields raise BlpValidationError
validate_fields=False	No validation for this call
validate_fields=None (default)	Follow the engine's validation_mode: 'disabled' (default), 'lenient' (log a warning and continue), or 'strict'

import xbbg
from xbbg import blp

xbbg.configure(validation_mode='lenient')
df = blp.bdp('AAPL US Equity', ['PX_LAST', 'NOT_A_FIELD'], validate_fields=True)  # raises

Security errors in results

By default a security Bloomberg rejects is simply missing from a bdp() result (a request in which every security fails raises BlpRequestError). With include_security_errors=True, each rejected security gets a row with field __SECURITY_ERROR__ and the error text as its value:

from xbbg import blp

df = blp.bdp(['AAPL US Equity', 'NOT_A_TICKER Equity'], 'PX_LAST', include_security_errors=True)

The same details are always available as security_errors result metadata on native, PyArrow, and pandas results.

Sharding wide requests

For wide multi-security bdp()/bdh() calls, the engine can split one request into concurrent chunks. It is off by default:

import xbbg

xbbg.configure(
    request_pool_size=6,
    shard_requests=True,
    shard_threshold=20,      # shard only requests with at least 20 securities
    shard_chunk_size=16,     # at most 16 securities per shard
    shard_max_concurrent=4,  # at most 4 shards in flight per call
)

Sharding applies to reference-data and historical requests (bdp, bdh, and generic requests of those operations). Results come back in the original security order, with entitlement IDs, security errors, field exceptions, and RequestIds merged across shards. Requests with per-security overrides are always split along override runs, and those runs are also capped at shard_chunk_size when sharding is enabled.

BQL application context

bql() and abql() take app_name=, which sets the BQL request's clientContext.appName for that call; configure(bql_app_name=...) sets an engine-wide default. With neither, xbbg omits the element and Bloomberg's default applies. This is unrelated to authentication's app_name.

from xbbg import blp

result = blp.bql("get(px_last) for('AAPL US Equity')", app_name='example-authorized-bql-app')

Other per-request options

Option	Helpers	Covered in
return_eids=True	bdp, bds, bdh, bdib, bdtick	Entitlements and Delayed Data
on_delayed='warn' / 'raise' / 'ignore'	bdp, bdh, bdib, bdtick	Entitlements and Delayed Data
request_tz, output_tz	bdib, bdtick	Dates and Datetimes
format	bdp, bdh, request	Output Formats
backend	all helpers	DataFrame Backends