---
url: 'https://xbbg.org/javascript/api/core.md'
---
## Classes
* [BlpError](/javascript/api/core/classes/blperror/)
* [BlpInternalError](/javascript/api/core/classes/blpinternalerror/)
* [BlpRequestError](/javascript/api/core/classes/blprequesterror/)
* [BlpSessionError](/javascript/api/core/classes/blpsessionerror/)
* [BlpTimeoutError](/javascript/api/core/classes/blptimeouterror/)
* [BlpValidationError](/javascript/api/core/classes/blpvalidationerror/)
* [Engine](/javascript/api/core/classes/engine/)
* [Subscription](/javascript/api/core/classes/subscription/)
## Interfaces
* [ActiveCdxOptions](/javascript/api/core/interfaces/activecdxoptions/)
* [BdhOptions](/javascript/api/core/interfaces/bdhoptions/)
* [BdibOptions](/javascript/api/core/interfaces/bdiboptions/)
* [BdpOptions](/javascript/api/core/interfaces/bdpoptions/)
* [BdtickOptions](/javascript/api/core/interfaces/bdtickoptions/)
* [BeqsOptions](/javascript/api/core/interfaces/beqsoptions/)
* [BfldsOptions](/javascript/api/core/interfaces/bfldsoptions/)
* [BlkpOptions](/javascript/api/core/interfaces/blkpoptions/)
* [BlpNamespace](/javascript/api/core/interfaces/blpnamespace/)
* [BqlOptions](/javascript/api/core/interfaces/bqloptions/)
* [BqrOptions](/javascript/api/core/interfaces/bqroptions/)
* [BsrchOptions](/javascript/api/core/interfaces/bsrchoptions/)
* [BtaOptions](/javascript/api/core/interfaces/btaoptions/)
* [CdxNamespace](/javascript/api/core/interfaces/cdxnamespace/)
* [CdxOptions](/javascript/api/core/interfaces/cdxoptions/)
* [CdxTickerInfo](/javascript/api/core/interfaces/cdxtickerinfo/)
* [CorporateBondsOptions](/javascript/api/core/interfaces/corporatebondsoptions/)
* [DividendOptions](/javascript/api/core/interfaces/dividendoptions/)
* [EngineConfig](/javascript/api/core/interfaces/engineconfig/)
* [EtfHoldingsOptions](/javascript/api/core/interfaces/etfholdingsoptions/)
* [ExchangeInfoResult](/javascript/api/core/interfaces/exchangeinforesult/)
* [ExchangeOverrideInput](/javascript/api/core/interfaces/exchangeoverrideinput/)
* [ExtNamespace](/javascript/api/core/interfaces/extnamespace/)
* [FieldInfo](/javascript/api/core/interfaces/fieldinfo/)
* [FuturesCandidate](/javascript/api/core/interfaces/futurescandidate/)
* [FuturesResolveOptions](/javascript/api/core/interfaces/futuresresolveoptions/)
* [FxPairInfo](/javascript/api/core/interfaces/fxpairinfo/)
* [MarketRule](/javascript/api/core/interfaces/marketrule/)
* [PreferredsOptions](/javascript/api/core/interfaces/preferredsoptions/)
* [RecipeBackendOptions](/javascript/api/core/interfaces/recipebackendoptions/)
* [RequestInput](/javascript/api/core/interfaces/requestinput/)
* [RequestOptions](/javascript/api/core/interfaces/requestoptions/)
* [RetryPolicy](/javascript/api/core/interfaces/retrypolicy/)
* [ServerAddress](/javascript/api/core/interfaces/serveraddress/)
* [SessionWindowsInfo](/javascript/api/core/interfaces/sessionwindowsinfo/)
* [Socks5Config](/javascript/api/core/interfaces/socks5config/)
* [StreamOptions](/javascript/api/core/interfaces/streamoptions/)
* [StringPair](/javascript/api/core/interfaces/stringpair/)
* [SubscriptionStats](/javascript/api/core/interfaces/subscriptionstats/)
* [TickerParts](/javascript/api/core/interfaces/tickerparts/)
* [TimeRange](/javascript/api/core/interfaces/timerange/)
* [TlsConfig](/javascript/api/core/interfaces/tlsconfig/)
* [TurnoverOptions](/javascript/api/core/interfaces/turnoveroptions/)
* [YasOptions](/javascript/api/core/interfaces/yasoptions/)
## Type Aliases
* [AuthConfig](/javascript/api/core/type-aliases/authconfig/)
## Variables
* [Backend](/javascript/api/core/variables/backend/)
* [blp](/javascript/api/core/variables/blp/)
* [ext](/javascript/api/core/variables/ext/)
* [Format](/javascript/api/core/variables/format/)
## Functions
* [abdh](/javascript/api/core/functions/abdh/)
* [abdib](/javascript/api/core/functions/abdib/)
* [abdp](/javascript/api/core/functions/abdp/)
* [abds](/javascript/api/core/functions/abds/)
* [abdtick](/javascript/api/core/functions/abdtick/)
* [asubscribe](/javascript/api/core/functions/asubscribe/)
* [bdh](/javascript/api/core/functions/bdh/)
* [bdib](/javascript/api/core/functions/bdib/)
* [bdp](/javascript/api/core/functions/bdp/)
* [bds](/javascript/api/core/functions/bds/)
* [bdtick](/javascript/api/core/functions/bdtick/)
* [configure](/javascript/api/core/functions/configure/)
* [connect](/javascript/api/core/functions/connect/)
* [getLogLevel](/javascript/api/core/functions/getloglevel/)
* [setLogLevel](/javascript/api/core/functions/setloglevel/)
* [subscribe](/javascript/api/core/functions/subscribe/)
* [version](/javascript/api/core/functions/version/)
* [wrapError](/javascript/api/core/functions/wraperror/)
---
---
url: 'https://xbbg.org/404.md'
description: The page you requested is not part of the public xbbg documentation.
---
## Try one of these public entry points
::: info Package Map
Compare the public packages in the monorepo and choose the right surface for your workflow.
```
[Open package map](/overview/package-map/)
```
:::
::: info Python docs
Open `xbbg` documentation for Python workflows backed by the same high-performance Rust core as the Node.js package.
```
[Open Python docs](/python/)
```
:::
::: info JavaScript docs
Explore `@xbbg/core`, the public Node.js package backed by the shared Rust engine.
```
[Open JavaScript docs](/javascript/)
```
:::
If you followed an old link, the project moved from a flatter docs layout to public package sections under `/python/`, `/javascript/`, and `/overview/`.
---
---
url: 'https://xbbg.org/javascript/api/core/functions/abdh.md'
---
> **abdh**(`tickers`, `fields`, `start?`, `end?`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:759`)
## Parameters
### tickers
`string` | `string`\[]
### fields
`string` | `string`\[]
### start?
`string`
### end?
`string`
### options?
[`BdhOptions`](/javascript/api/core/interfaces/bdhoptions/)
## Returns
`Promise`<`Table`<`any`>>
---
---
url: 'https://xbbg.org/javascript/api/core/functions/abdib.md'
---
> **abdib**(`ticker`, `dt?`, `interval?`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:772`)
## Parameters
### ticker
`string`
### dt?
`string`
### interval?
`number`
### options?
[`BdibOptions`](/javascript/api/core/interfaces/bdiboptions/)
## Returns
`Promise`<`Table`<`any`>>
---
---
url: 'https://xbbg.org/javascript/api/core/functions/abdp.md'
---
> **abdp**(`tickers`, `fields`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:754`)
## Parameters
### tickers
`string` | `string`\[]
### fields
`string` | `string`\[]
### options?
[`BdpOptions`](/javascript/api/core/interfaces/bdpoptions/)
## Returns
`Promise`<`Table`<`any`>>
---
---
url: 'https://xbbg.org/javascript/api/core/functions/abds.md'
---
> **abds**(`tickers`, `fields`, `overrides?`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:766`)
## Parameters
### tickers
`string` | `string`\[]
### fields
`string` | `string`\[]
### overrides?
`Record`<`string`, `string` | `number` | `boolean`>
### options?
[`BdpOptions`](/javascript/api/core/interfaces/bdpoptions/)
## Returns
`Promise`<`Table`<`any`>>
---
---
url: 'https://xbbg.org/javascript/api/core/functions/abdtick.md'
---
> **abdtick**(`ticker`, `start`, `end`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:778`)
## Parameters
### ticker
`string`
### start
`string`
### end
`string`
### options?
[`BdtickOptions`](/javascript/api/core/interfaces/bdtickoptions/)
## Returns
`Promise`<`Table`<`any`>>
---
---
url: 'https://xbbg.org/javascript/api/core/interfaces/activecdxoptions.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:270`)
## Properties
### backend?
> `optional` **backend?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:272`)
***
### lookbackDays?
> `optional` **lookbackDays?**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:271`)
---
---
url: 'https://xbbg.org/overview/architecture.md'
description: How xbbg keeps Python and Node.js on one licensed-data engine
---
## Public surfaces
Internal Rust crates, binding crates, native platform npm packages, and private packages are implementation details. Users choose one of the public packages; the runtime underneath stays the same.
## Shared request path
## Runtime responsibilities
## Configuration is explicit
Connection settings are system-level facts. xbbg keeps local Terminal, B-PIPE, SAPI auth, TLS, ZFP, SOCKS5, retry, and failover settings in configuration rather than hiding them in individual request helpers.
That makes production assumptions visible to reviewers, operators, and application owners.
---
---
url: 'https://xbbg.org/javascript/api/core/functions/asubscribe.md'
---
> **asubscribe**(`tickers`, `fields`): `Promise`<[`Subscription`](/javascript/api/core/classes/subscription/)>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:784`)
## Parameters
### tickers
`string` | `string`\[]
### fields
`string` | `string`\[]
## Returns
`Promise`<[`Subscription`](/javascript/api/core/classes/subscription/)>
---
---
url: 'https://xbbg.org/python/guides/async.md'
description: Concurrent Bloomberg requests with async/await
---
xbbg v1 is async-first. Every data function has an `async` counterpart: `bdp()` → `abdp()`, `bdh()` → `abdh()`, `bdib()` → `abdib()`, and so on.
## Architecture
Under the hood, xbbg runs a Rust async engine with pre-warmed worker pools. Each request worker holds an independent Bloomberg session, and concurrent calls are dispatched round-robin:
```
┌─────────────────────────────────────────────────┐
│ xbbg Engine │
│ │
│ ┌──────────────────────┐ ┌─────────────────┐ │
│ │ Request Worker Pool │ │ Subscription │ │
│ │ (request_pool_size) │ │ Session Pool │ │
│ │ │ │ (sub_pool_size) │ │
│ │ Worker 1 ──session │ │ │ │
│ │ Worker 2 ──session │ │ Session 1 │ │
│ │ ... │ │ ... │ │
│ └──────────────────────┘ └─────────────────┘ │
│ │ round-robin │ isolated │
│ ▼ ▼ │
│ bdp/bdh/bds/bdib subscribe/stream │
└─────────────────────────────────────────────────┘
```
With `request_pool_size=2` (the default), two Bloomberg requests can run in parallel at the session level. Raising the pool size allows more simultaneous requests.
### Sync/async function mapping
| Sync | Async |
|------|-------|
| `bdp()` | `abdp()` |
| `bdh()` | `abdh()` |
| `bds()` | `abds()` |
| `bdib()` | `abdib()` |
| `bdtick()` | `abdtick()` |
| `request()` | `arequest()` |
All async functions accept identical parameters to their sync equivalents and return the same DataFrame types.
## Basic usage in scripts
In a plain script or application (no existing event loop), use `asyncio.run()`:
```python
import asyncio
from xbbg import blp
async def get_data():
df = await blp.abdp(tickers='AAPL US Equity', flds=['PX_LAST', 'VOLUME'])
return df
data = asyncio.run(get_data())
```
## Concurrent requests
`asyncio.gather()` runs multiple Bloomberg requests in parallel on a single thread. Requests are dispatched across the worker pool simultaneously rather than sequentially:
```python
import asyncio
from xbbg import blp
async def get_multiple():
results = await asyncio.gather(
blp.abdp(tickers='AAPL US Equity', flds=['PX_LAST']),
blp.abdp(tickers='MSFT US Equity', flds=['PX_LAST']),
blp.abdh(tickers='GOOGL US Equity', flds=['PX_LAST'], start_date='2024-01-01'),
)
return results # list of DataFrames, one per awaitable
results = asyncio.run(get_multiple())
```
The three requests above are dispatched at once. With the default `request_pool_size=2`, two run immediately and the third waits for a free worker. Increase the pool size to raise the concurrency ceiling:
```python
from xbbg import configure
configure(request_pool_size=4)
```
## Jupyter notebooks
Jupyter and VS Code Interactive run an IPykernel event loop. For one-shot request/response APIs, the sync wrappers keep the familiar Bloomberg syntax working by using a notebook-only background event-loop bridge:
```python
from xbbg import blp
# Sync one-shot calls work in notebook cells
df = blp.bdp(tickers='AAPL US Equity', flds=['PX_LAST', 'VOLUME'])
hist = blp.bdh(tickers='AAPL US Equity', flds=['PX_LAST'], start_date='2024-01-01')
```
The bridge applies to `bdp`, `bdh`, `bds`, `bdib`, `bdtick`, and `request`. It preserves scoped `xbbg.Engine(...)` context across the background thread and propagates exceptions back to the cell.
If you are already writing async notebook code, keep using top-level `await`:
```python
from xbbg import blp
df = await blp.abdp(tickers='AAPL US Equity', flds=['PX_LAST', 'VOLUME'])
```
::: warning
The notebook bridge is not a generic async escape hatch. FastAPI, ASGI services, task workers, and other async applications should use the `a`-prefixed APIs directly. Streaming and long-lived lifecycle APIs also remain explicitly async-aware.
:::
## GIL release
The Rust engine releases the Python GIL while waiting for Bloomberg I/O. This means Python threads can execute concurrently during a Bloomberg request — CPU-bound Python work is not blocked while requests are in flight. In practice:
* A `asyncio.gather()` over multiple Bloomberg calls does not serialize behind the GIL.
* Threads running independent Python work alongside Bloomberg requests are not stalled waiting for network responses.
This is a property of the Rust/PyO3 integration, not Python's asyncio scheduler.
## Error handling
All xbbg exceptions inherit from `BlpError`, which lets you catch any Bloomberg-related failure with a single clause. The hierarchy:
| Exception | When raised |
|-----------|-------------|
| `BlpSessionError` | Session start, connect, or service open failure |
| `BlpRequestError` | Request-level error returned by Bloomberg |
| `BlpSecurityError` | Invalid or inaccessible security identifier |
| `BlpFieldError` | Invalid or inaccessible field name |
| `BlpTimeoutError` | Request timed out |
| `BlpValidationError` | Field validation failure (strict mode) |
| `BlpInternalError` | Internal engine error |
### Single request
```python
import asyncio
from xbbg import blp
from xbbg.exceptions import BlpSecurityError, BlpError
async def safe_fetch(ticker: str):
try:
return await blp.abdp(tickers=ticker, flds=['PX_LAST'])
except BlpSecurityError as e:
print(f"Unknown security: {ticker} — {e}")
return None
except BlpError as e:
print(f"Bloomberg error: {e}")
raise
asyncio.run(safe_fetch('INVALID US Equity'))
```
### Concurrent requests with partial failures
By default, `asyncio.gather()` cancels all pending awaitables and re-raises the first exception. Pass `return_exceptions=True` to collect results and errors together instead:
```python
import asyncio
from xbbg import blp
from xbbg.exceptions import BlpError
async def fetch_all(tickers: list[str]):
results = await asyncio.gather(
*[blp.abdp(tickers=t, flds=['PX_LAST']) for t in tickers],
return_exceptions=True,
)
for ticker, result in zip(tickers, results):
if isinstance(result, BlpError):
print(f"Failed: {ticker} — {result}")
else:
print(f"OK: {ticker}, rows={len(result)}")
asyncio.run(fetch_all(['AAPL US Equity', 'INVALID', 'MSFT US Equity']))
```
::: warning
With `return_exceptions=True`, exceptions are returned as values in the results list — they are not raised. Check each result with `isinstance(result, Exception)` before using it.
:::
## Best practices
**Batch tickers in a single call instead of many parallel calls.**
`abdp()` and `abdh()` accept a list of tickers. A single call with `['AAPL US Equity', 'MSFT US Equity', 'GOOGL US Equity']` is more efficient than three parallel calls — it sends one Bloomberg request and Bloomberg returns results for all tickers together.
```python
# Preferred: one request, many tickers
df = await blp.abdp(
tickers=['AAPL US Equity', 'MSFT US Equity', 'GOOGL US Equity'],
flds=['PX_LAST', 'VOLUME'],
)
# Use gather when requests are genuinely different (different fields, dates, services)
results = await asyncio.gather(
blp.abdp(tickers=['AAPL US Equity', 'MSFT US Equity'], flds=['PX_LAST']),
blp.abdh(tickers='AAPL US Equity', flds=['PX_LAST'], start_date='2024-01-01'),
)
```
**Use async when integrating with async frameworks.**
If you are building a FastAPI service, ASGI app, async task queue, or other async application, prefer the `a`-prefixed functions — they participate in the event loop without blocking it. Sync wrappers still raise in these generic async contexts and direct you to `await abdp(...)`, `await abdh(...)`, and the other async APIs.
**Sync functions work in scripts and notebooks.**
If your script is sequential and you have no async requirements, the sync functions (`bdp`, `bdh`, `bdib`, etc.) are fully supported. In IPykernel notebooks and VS Code Interactive, one-shot sync calls use a background loop bridge; outside notebooks, sync wrappers use `asyncio.run()`.
**Match pool size to workload.**
The default `request_pool_size=2` is appropriate for most workloads. If you are issuing many concurrent `gather()` calls with large fan-outs, raise it — but Bloomberg API servers also have per-connection limits, so test before committing to a large value.
For the full API reference, see [Bloomberg Data API](/python/api/blp/).
---
---
url: 'https://xbbg.org/javascript/api/core/type-aliases/authconfig.md'
---
> **AuthConfig** = { `method`: `"user"`; } | { `appName`: `string`; `method`: `"app"`; } | { `appName`: `string`; `method`: `"userapp"`; } | { `dirProperty`: `string`; `method`: `"dir"` | `"directory"`; } | { `appName`: `string`; `ipAddress`: `string`; `method`: `"manual"`; `userId`: `string`; } | { `method`: `"token"`; `token`: `string`; }
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:15`)
---
---
url: 'https://xbbg.org/javascript/api/core/variables/backend.md'
---
> `const` **Backend**: `Readonly`<{ `ARROW`: `"arrow"`; `JSON`: `"json"`; `POLARS`: `"polars"`; }>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:186`)
---
---
url: 'https://xbbg.org/javascript/api/core/functions/bdh.md'
---
> **bdh**(`tickers`, `fields`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:738`)
## Parameters
### tickers
`string` | `string`\[]
### fields
`string` | `string`\[]
### options?
[`BdhOptions`](/javascript/api/core/interfaces/bdhoptions/)
## Returns
`Promise`<`Table`<`any`>>
---
---
url: 'https://xbbg.org/javascript/api/core/interfaces/bdhoptions.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:137`)
## Properties
### backend?
> `optional` **backend?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:143`)
***
### end?
> `optional` **end?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:139`)
***
### format?
> `optional` **format?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:142`)
***
### kwargs?
> `optional` **kwargs?**: `Record`<`string`, `string` | `number` | `boolean`>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:141`)
***
### overrides?
> `optional` **overrides?**: `Record`<`string`, `string` | `number` | `boolean`>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:140`)
***
### start?
> `optional` **start?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:138`)
---
---
url: 'https://xbbg.org/javascript/api/core/functions/bdib.md'
---
> **bdib**(`ticker`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:748`)
## Parameters
### ticker
`string`
### options?
[`BdibOptions`](/javascript/api/core/interfaces/bdiboptions/)
## Returns
`Promise`<`Table`<`any`>>
---
---
url: 'https://xbbg.org/javascript/api/core/interfaces/bdiboptions.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:146`)
## Properties
### backend?
> `optional` **backend?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:152`)
***
### end?
> `optional` **end?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:148`)
***
### eventType?
> `optional` **eventType?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:149`)
***
### interval?
> `optional` **interval?**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:150`)
***
### kwargs?
> `optional` **kwargs?**: `Record`<`string`, `string` | `number` | `boolean`>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:151`)
***
### start?
> `optional` **start?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:147`)
---
---
url: 'https://xbbg.org/javascript/api/core/functions/bdp.md'
---
> **bdp**(`tickers`, `fields`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:733`)
## Parameters
### tickers
`string` | `string`\[]
### fields
`string` | `string`\[]
### options?
[`BdpOptions`](/javascript/api/core/interfaces/bdpoptions/)
## Returns
`Promise`<`Table`<`any`>>
---
---
url: 'https://xbbg.org/javascript/api/core/interfaces/bdpoptions.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:129`)
## Extended by
* [`CdxOptions`](/javascript/api/core/interfaces/cdxoptions/)
## Properties
### backend?
> `optional` **backend?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:133`)
***
### format?
> `optional` **format?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:132`)
***
### includeSecurityErrors?
> `optional` **includeSecurityErrors?**: `boolean`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:134`)
***
### kwargs?
> `optional` **kwargs?**: `Record`<`string`, `string` | `number` | `boolean`>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:131`)
***
### overrides?
> `optional` **overrides?**: `Record`<`string`, `string` | `number` | `boolean`>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:130`)
---
---
url: 'https://xbbg.org/javascript/api/core/functions/bds.md'
---
> **bds**(`tickers`, `fields`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:743`)
## Parameters
### tickers
`string` | `string`\[]
### fields
`string` | `string`\[]
### options?
[`BdpOptions`](/javascript/api/core/interfaces/bdpoptions/)
## Returns
`Promise`<`Table`<`any`>>
---
---
url: 'https://xbbg.org/javascript/api/core/functions/bdtick.md'
---
> **bdtick**(`ticker`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:749`)
## Parameters
### ticker
`string`
### options?
[`BdtickOptions`](/javascript/api/core/interfaces/bdtickoptions/)
## Returns
`Promise`<`Table`<`any`>>
---
---
url: 'https://xbbg.org/javascript/api/core/interfaces/bdtickoptions.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:155`)
## Properties
### backend?
> `optional` **backend?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:160`)
***
### end?
> `optional` **end?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:157`)
***
### eventTypes?
> `optional` **eventTypes?**: `string`\[]
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:158`)
***
### kwargs?
> `optional` **kwargs?**: `Record`<`string`, `string` | `number` | `boolean`>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:159`)
***
### start?
> `optional` **start?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:156`)
---
---
url: 'https://xbbg.org/javascript/api/core/interfaces/beqsoptions.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:203`)
## Properties
### asof?
> `optional` **asof?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:204`)
***
### backend?
> `optional` **backend?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:210`)
***
### format?
> `optional` **format?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:209`)
***
### group?
> `optional` **group?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:206`)
***
### kwargs?
> `optional` **kwargs?**: `Record`<`string`, `string` | `number` | `boolean`>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:208`)
***
### overrides?
> `optional` **overrides?**: `Record`<`string`, `string` | `number` | `boolean`>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:207`)
***
### screenType?
> `optional` **screenType?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:205`)
---
---
url: 'https://xbbg.org/javascript/api/core/interfaces/bfldsoptions.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:228`)
## Properties
### backend?
> `optional` **backend?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:233`)
***
### fields?
> `optional` **fields?**: `string` | `string`\[]
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:229`)
***
### format?
> `optional` **format?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:232`)
***
### kwargs?
> `optional` **kwargs?**: `Record`<`string`, `string` | `number` | `boolean`>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:231`)
***
### searchSpec?
> `optional` **searchSpec?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:230`)
---
---
url: 'https://xbbg.org/javascript/api/core/interfaces/blkpoptions.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:235`)
## Properties
### backend?
> `optional` **backend?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:238`)
***
### format?
> `optional` **format?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:237`)
***
### kwargs?
> `optional` **kwargs?**: `Record`<`string`, `string` | `number` | `boolean`>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:236`)
---
---
url: 'https://xbbg.org/python/api/blp.md'
description: 'Core API functions for Bloomberg data (bdp, bdh, bds, bdib, bdtick)'
---
# xbbg.blp
High-level Bloomberg data API: reference, historical, intraday.
This module provides the xbbg-compatible API using the Rust backend,
with support for multiple DataFrame backends via narwhals.
API Design:
* Async-first: Core implementation uses async/await (abdp, abdh, etc.)
* Sync wrappers: Convenience functions (bdp, bdh, etc.) wrap async with asyncio.run()
* Generic API: arequest() and request() for power users and arbitrary Bloomberg requests
* Users can use either style based on their needs
## Engine Objects
```python
class Engine()
```
Non-global Bloomberg engine for multi-source routing.
Use as a context manager to scope all `blp.*` calls to this engine:
```
engine = blp.Engine(host="bpipe.firm.com", auth_method="app", app_name="myapp")
with engine:
df = blp.bdp(...) # uses this engine, not the global
```
Or pass directly to individual calls:
```
df = blp.bdp(..., engine=engine)
```
The global `configure()` + `blp.bdp()` API is unaffected.
## RequestEnvironment Objects
```python
@dataclass(frozen=True, slots=True)
class RequestEnvironment()
```
Read-only engine and auth snapshot available to request middleware.
## RequestContext Objects
```python
@dataclass(slots=True)
class RequestContext()
```
Mutable context object passed through the request middleware chain.
#### add\_middleware
```python
def add_middleware(middleware: RequestMiddleware) -> RequestMiddleware
```
Register a request middleware callable.
Middleware is called as `middleware(context, call_next)` and may be sync or async.
Returning the middleware makes this usable as a decorator.
#### remove\_middleware
```python
def remove_middleware(middleware: RequestMiddleware) -> None
```
Remove a previously registered middleware callable.
#### clear\_middleware
```python
def clear_middleware() -> None
```
Remove all registered middleware.
#### get\_middleware
```python
def get_middleware() -> tuple[RequestMiddleware, ...]
```
Return the currently registered middleware chain.
#### set\_middleware
```python
def set_middleware(middleware: Sequence[RequestMiddleware]) -> None
```
Replace the current middleware chain.
#### shutdown
```python
def shutdown() -> None
```
Signal the Bloomberg engine to shutdown.
Signals all worker threads to stop. They will terminate when they
finish their current work or see the shutdown signal.
This is called automatically during Python interpreter shutdown.
You usually don't need to call this directly.
Example::
````python
def reset() -> None
```python
def is_connected() -> bool
```python
def configure(config=None, **kwargs) -> None
See ``EngineConfig()`` for available fields and their defaults::
>>> from xbbg import EngineConfig
>>> EngineConfig()
EngineConfig(host='localhost', port=8194, request_pool_size=2,
subscription_pool_size=1, ...)
**Arguments**:
- `config` - An EngineConfig object with all settings.
- `**kwargs` - Override individual fields (host, port, request_pool_size,
subscription_pool_size, field_cache_path, auth_method, app_name,
user_id, ip_address, token, etc.).
**Raises**:
- `TypeError` - If an unknown keyword argument is passed.
- `ValueError` - If `num_start_attempts` is less than 1.
- `RuntimeWarning` - If called after the engine has already started
(the existing engine is shut down and will restart with the new config).
Example::
```python
def set_backend(backend: Backend | str | None) -> None
```python
def get_backend() -> Backend | None
```python
async def arequest(
service: str | Service,
operation: str | Operation,
*,
request_operation: str | Operation | None = None,
securities: str | Sequence[str] | None = None,
security: str | None = None,
fields: str | Sequence[str] | None = None,
overrides: dict[str, Any] | Sequence[tuple[str, str]] | None = None,
elements: Sequence[tuple[str, Any]] | None = None,
start_date: str | None = None,
end_date: str | None = None,
start_datetime: str | None = None,
end_datetime: str | None = None,
event_type: str | None = None,
event_types: Sequence[str] | None = None,
interval: int | None = None,
options: dict[str, Any] | Sequence[tuple[str, str]] | None = None,
field_types: dict[str, str] | None = None,
output: OutputMode | str = OutputMode.ARROW,
extractor: ExtractorHint | str | None = None,
format: Format | str | None = None,
include_security_errors: bool = False,
validate_fields: bool | None = None,
backend: Backend | str | None = None,
request_tz: str | None = None,
output_tz: str | None = None,
_raw: bool = False)
- `format` - Output format hint for result structure.
- `include_security_errors` - Include ``__SECURITY_ERROR__`` rows for
failed securities on ReferenceData requests.
- `validate_fields` - Optional per-request override for field validation.
``True`` forces strict validation, ``False`` disables it, and
``None`` follows engine-level validation mode.
- `backend` - DataFrame backend to return. If None, uses global default.
**Returns**:
DataFrame/Table in the requested format.
Example::
# Query field metadata (//blp/apiflds service)
df = await arequest(
Service.APIFLDS,
Operation.FIELD_INFO,
fields=["PX_LAST", "VOLUME"],
)
# Get raw JSON for debugging
json_table = await arequest(
Service.REFDATA,
Operation.REFERENCE_DATA,
securities=["AAPL US Equity"],
fields=["PX_LAST"],
output=OutputMode.JSON,
)
# Custom Bloomberg request (power user)
df = await arequest(
"//blp/refdata",
"ReferenceDataRequest",
securities=["AAPL US Equity"],
fields=["PX_LAST"],
)
# Raw request marker with explicit Bloomberg operation
df = await arequest(
Service.REFDATA,
Operation.RAW_REQUEST,
request_operation=Operation.REFERENCE_DATA,
extractor=ExtractorHint.REFDATA,
securities=["AAPL US Equity"],
fields=["PX_LAST"],
)
#### abdp
```python
async def abdp(tickers: str | Sequence[str],
flds: str | Sequence[str] | None = None,
*,
backend: Backend | str | None = None,
format: Format | str | None = None,
field_types: dict[str, str] | None = None,
include_security_errors: bool = False,
validate_fields: bool | None = None,
**kwargs)
````
Async Bloomberg reference data (BDP).
**Arguments**:
* `tickers` - Single ticker or list of tickers.
* `flds` - Single field or list of fields to query.
* `backend` - DataFrame backend to return. If None, uses global default.
Supports lazy backends: 'polars\_lazy', 'narwhals\_lazy', 'duckdb'.
* `format` - Output format. Options:
* Format.LONG (default): ticker, field, value (strings)
* Format.LONG\_TYPED: ticker, field, value\_f64, value\_i64, etc.
* Format.LONG\_WITH\_METADATA: ticker, field, value, dtype
* `field_types` - Manual type overrides for fields (e.g., {'VOLUME': 'int64'}).
If None, types are auto-resolved from Bloomberg field metadata.
* `include_security_errors` - Include `__SECURITY_ERROR__` rows for
securities that Bloomberg rejected.
* `validate_fields` - Optional per-request override for field validation.
`True` forces strict validation, `False` disables it, and
`None` follows engine-level validation mode.
* `**kwargs` - Bloomberg overrides and infrastructure options.
**Returns**:
DataFrame in long format with columns: ticker, field, value.
For lazy backends, returns LazyFrame that must be collected.
Example::
# Async usage
df = await abdp("AAPL US Equity", \["PX\_LAST", "VOLUME"])
# Concurrent requests
dfs = await asyncio.gather(
abdp("AAPL US Equity", "PX\_LAST"),
abdp("MSFT US Equity", "PX\_LAST"),
)
#### abdh
```python
async def abdh(tickers: str | Sequence[str],
flds: str | Sequence[str] | None = None,
start_date: str | None = None,
end_date: str = "today",
*,
backend: Backend | str | None = None,
format: Format | str | None = None,
field_types: dict[str, str] | None = None,
validate_fields: bool | None = None,
**kwargs)
```
Async Bloomberg historical data (BDH).
**Arguments**:
* `tickers` - Single ticker or list of tickers.
* `flds` - Single field or list of fields. Defaults to \['PX\_LAST'].
* `start_date` - Start date. Defaults to 8 weeks before end\_date.
* `end_date` - End date. Defaults to 'today'.
* `backend` - DataFrame backend to return. If None, uses global default.
Supports lazy backends: 'polars\_lazy', 'narwhals\_lazy', 'duckdb'.
* `format` - Output format. Options:
* Format.LONG (default): ticker, date, field, value (strings)
* Format.LONG\_TYPED: ticker, date, field, value\_f64, value\_i64, etc.
* Format.LONG\_WITH\_METADATA: ticker, date, field, value, dtype
* `field_types` - Manual type overrides for fields (e.g., {'VOLUME': 'int64'}).
If None, types are auto-resolved from Bloomberg field metadata.
* `validate_fields` - Optional per-request override for field validation.
`True` forces strict validation, `False` disables it, and
`None` follows engine-level validation mode.
* `**kwargs` - Additional overrides and infrastructure options.
* `adjust` - Adjustment type ('all', 'dvd', 'split', '-', None).
**Returns**:
DataFrame in long format with columns: ticker, date, field, value.
For lazy backends, returns LazyFrame that must be collected.
Example::
# Async usage
df = await abdh("AAPL US Equity", "PX\_LAST", start\_date="2024-01-01")
# Concurrent requests
dfs = await asyncio.gather(
abdh("AAPL US Equity", "PX\_LAST"),
abdh("MSFT US Equity", "PX\_LAST"),
)
#### abds
```python
async def abds(tickers: str | Sequence[str],
flds: str,
*,
backend: Backend | str | None = None,
validate_fields: bool | None = None,
**kwargs)
```
Async Bloomberg bulk data (BDS).
**Arguments**:
* `tickers` - Single ticker or list of tickers.
* `flds` - Single field name (bulk fields return multiple rows).
* `backend` - DataFrame backend to return. If None, uses global default.
* `validate_fields` - Optional per-request override for field validation.
`True` forces strict validation, `False` disables it, and
`None` follows engine-level validation mode.
* `**kwargs` - Bloomberg overrides and infrastructure options.
**Returns**:
DataFrame with bulk data, multiple rows per ticker.
Example::
df = await abds("AAPL US Equity", "DVD\_Hist\_All")
df = await abds("SPX Index", "INDX\_MEMBERS", backend="polars")
#### abdib
```python
async def abdib(ticker: str,
dt: str | None = None,
session: str = "allday",
typ: str = "TRADE",
*,
start_datetime: str | None = None,
end_datetime: str | None = None,
interval: int = 1,
backend: Backend | str | None = None,
request_tz: str | None = None,
output_tz: str | None = None,
**kwargs)
```
Async Bloomberg intraday bar data (BDIB).
**Arguments**:
* `ticker` - Ticker name.
* `dt` - Date to download (for single-day requests).
* `session` - Trading session name. Ignored when start\_datetime/end\_datetime provided.
* `typ` - Event type (TRADE, BID, ASK, etc.).
* `start_datetime` - Explicit start datetime for multi-day requests.
* `end_datetime` - Explicit end datetime for multi-day requests.
* `interval` - Bar interval in minutes (default: 1), or seconds if intervalHasSeconds=True.
* `backend` - DataFrame backend to return. If None, uses global default.
* `request_tz` - How naive `start_datetime` / `end_datetime` (and full-day `dt` window)
are interpreted before Bloomberg: `UTC` (default when omitted), `local`,
`exchange` (uses this ticker), `NY`/`LN`/`TK`/`HK`, another ticker string,
or an IANA zone. Conversion to UTC is done in the Rust engine.
* `output_tz` - Relabel the `time` column to this zone (same instants; Rust engine).
* `**kwargs` - Additional Bloomberg options (e.g., intervalHasSeconds,
gapFillInitialBar). Pass field overrides via `overrides={"Points": 1}`
(dict) or `overrides=[("Points", 1)]` (list of tuples).
**Returns**:
DataFrame with intraday bar data.
Example::
# 1-minute bars (default)
df = await abdib("AAPL US Equity", dt="2024-12-01")
# 5-minute bars with explicit datetime range
df = await abdib(
"AAPL US Equity",
start\_datetime="2024-12-01 09:30",
end\_datetime="2024-12-01 16:00",
interval=5,
)
# 10-second bars
df = await abdib("AAPL US Equity", dt="2024-12-01", interval=10, intervalHasSeconds=True)
#### abdtick
```python
async def abdtick(ticker: str,
start_datetime: str,
end_datetime: str,
*,
event_types: Sequence[str] | None = None,
backend: Backend | str | None = None,
request_tz: str | None = None,
output_tz: str | None = None,
**kwargs)
```
Async Bloomberg tick data (BDTICK).
**Arguments**:
* `ticker` - Ticker name.
* `start_datetime` - Start datetime.
* `end_datetime` - End datetime.
* `event_types` - Event types to retrieve. Defaults to \["TRADE"].
* `Options` - TRADE, BID, ASK, BID\_BEST, ASK\_BEST, MID\_PRICE, AT\_TRADE, BEST\_BID, BEST\_ASK.
* `backend` - DataFrame backend to return. If None, uses global default.
* `request_tz` - How naive datetimes are interpreted before Bloomberg (see `abdib`).
* `output_tz` - Relabel `time` column (same instants; Rust engine).
* `**kwargs` - Additional Bloomberg options. Pass field overrides via
* \`\`\`overrides={"Points"\` - 1}`(dict) or`overrides=\[("Points", 1)]\`\`
(list of tuples). Schema-recognized request elements may be passed
as individual keyword arguments.
**Returns**:
DataFrame with tick data.
Example::
df = await abdtick("AAPL US Equity", "2024-12-01 09:30", "2024-12-01 10:00")
df = await abdtick(
"AAPL US Equity", "2024-12-01 09:30", "2024-12-01 10:00", event\_types=\["TRADE", "BID", "ASK"]
)
df = await abdtick("AAPL US Equity", "2024-12-01 09:30", "2024-12-01 10:00", backend="polars")
## Tick Objects
```python
@dataclass
class Tick()
```
Single tick data point from a subscription.
**Attributes**:
* `ticker` - Security identifier
* `field` - Bloomberg field name
* `value` - Field value (float, int, str, bool, datetime, or None)
* `timestamp` - Time the tick was received
## Subscription Objects
```python
class Subscription()
```
Subscription handle with async iteration and dynamic control.
Supports:
* Async iteration: `async for tick in sub`
* Dynamic add/remove: `await sub.add(['MSFT US Equity'])`
* Context manager: `async with xbbg.asubscribe(...) as sub:`
* Explicit unsubscribe: `await sub.unsubscribe(drain=True)`
Example::
sub = await xbbg.asubscribe(\["AAPL US Equity"], \["LAST\_PRICE", "BID"])
async for batch in sub:
# batch is pyarrow.RecordBatch
print(batch.to\_pandas())
if should\_add\_msft:
await sub.add(\["MSFT US Equity"])
await sub.unsubscribe()
#### \_\_init\_\_
```python
def __init__(py_sub,
raw: bool,
backend: Backend | None,
tick_mode: bool = False)
```
Initialize subscription wrapper.
**Arguments**:
* `py_sub` - The underlying PySubscription from Rust
* `raw` - If True, yield raw Arrow batches
* `backend` - DataFrame backend for conversion (if not raw)
* `tick_mode` - If True, convert batches to dicts (implies raw=True)
#### \_\_anext\_\_
```python
async def __anext__() -> pa.RecordBatch | nw.DataFrame | dict[str, Any]
```
Get next batch of data.
#### add
```python
async def add(tickers: str | list[str]) -> None
```
Add tickers to subscription dynamically.
**Arguments**:
* `tickers` - Single ticker or list of tickers to add
#### remove
```python
async def remove(tickers: str | list[str]) -> None
```
Remove tickers from subscription dynamically.
**Arguments**:
* `tickers` - Single ticker or list of tickers to remove
#### tickers
```python
@property
def tickers() -> list[str]
```
Currently active tickers.
#### failed\_tickers
```python
@property
def failed_tickers() -> list[str]
```
Tickers Bloomberg rejected or terminated.
#### failures
```python
@property
def failures() -> list[dict[str, str]]
```
Non-fatal per-ticker subscription failures.
Each entry contains:
\- ticker: Bloomberg topic string
\- reason: Bloomberg failure detail
\- kind: "failure" or "terminated"
#### topic\_states
```python
@property
def topic_states() -> dict[str, dict[str, int | str]]
```
Topic lifecycle state keyed by ticker/topic.
#### session\_status
```python
@property
def session_status() -> dict[str, int | str]
```
Session-level connection status for this subscription.
#### admin\_status
```python
@property
def admin_status() -> dict[str, int | bool | None]
```
Bloomberg admin/slow-consumer status for this subscription.
#### service\_status
```python
@property
def service_status() -> dict[str, dict[str, int | bool]]
```
Service availability status keyed by Bloomberg service name.
#### events
```python
@property
def events() -> list[dict[str, str | int | None]]
```
Bounded lifecycle/event history for the subscription.
#### status
```python
@property
def status() -> dict[str, Any]
```
Combined operational status snapshot.
#### fields
```python
@property
def fields() -> list[str]
```
Subscribed fields.
#### is\_active
```python
@property
def is_active() -> bool
```
Whether the subscription is still active.
#### all\_failed
```python
@property
def all_failed() -> bool
```
Whether every requested ticker has ended in failure/termination.
#### stats
```python
@property
def stats() -> dict
```
Subscription metrics.
**Returns**:
dict with keys:
* messages\_received: int - total messages received from Bloomberg
* dropped\_batches: int - batches dropped due to overflow
* batches\_sent: int - batches successfully sent to Python
* slow\_consumer: bool - True if DATALOSS was received
* data\_loss\_events: int - total Bloomberg data-loss signals observed
* last\_message\_us: int - latest receive timestamp seen from Bloomberg
* last\_data\_loss\_us: int - latest data-loss timestamp seen from Bloomberg
* effective\_overflow\_policy: str - actual runtime policy used by the Rust stream
#### unsubscribe
```python
async def unsubscribe(drain: bool = False) -> list[pa.RecordBatch] | None
```
Close subscription and optionally drain remaining data.
**Arguments**:
* `drain` - If True, return any remaining buffered batches
**Returns**:
List of remaining batches if drain=True, else None
#### asubscribe
```python
async def asubscribe(tickers: str | list[str],
fields: str | list[str],
*,
raw: bool = False,
all_fields: bool = False,
backend: Backend | str | None = None,
service: str | None = None,
options: list[str] | None = None,
tick_mode: bool = False,
flush_threshold: int | None = None,
stream_capacity: int | None = None,
overflow_policy: str | None = None) -> Subscription
```
Create an async subscription to real-time market data.
This is the low-level subscription API with full control over
the subscription lifecycle, including dynamic add/remove.
Subscription recovery is handled automatically by the Bloomberg SDK (see
BLPAPI ChangeLog v3.11.6); per-subscription availability transitions fire
as `SubscriptionStreamsActivated` / `SubscriptionStreamsDeactivated`
events which are reflected in `sub.topic_states` (`streams_active`).
**Arguments**:
* `tickers` - Securities to subscribe to
* `fields` - Fields to subscribe to (e.g., 'LAST\_PRICE', 'BID', 'ASK')
* `raw` - If True, yield raw Arrow RecordBatches for max performance
* `all_fields` - If True, expose all top-level scalar Bloomberg subscription fields
* `backend` - DataFrame backend for batch conversion (ignored if raw=True)
* `service` - Bloomberg service (e.g., '//blp/mktdata'). If provided, uses subscribe\_with\_options
* `options` - List of subscription options. If provided, uses subscribe\_with\_options
* `tick_mode` - If True, convert batches to dicts (implies raw=True)
* `flush_threshold` - Batch flush threshold (validation only in Wave 1)
* `stream_capacity` - Stream channel capacity (validation only in Wave 1)
* `overflow_policy` - Overflow policy for stream (validation only in Wave 1)
**Returns**:
Subscription handle for iteration and control
Example::
# Basic usage
sub = await xbbg.asubscribe(\["AAPL US Equity"], \["LAST\_PRICE", "BID"])
async for batch in sub:
print(batch)
await sub.unsubscribe()
# With context manager
async with xbbg.asubscribe(\["AAPL US Equity"], \["LAST\_PRICE"]) as sub:
count = 0
async for batch in sub:
print(batch)
count += 1
if count >= 10:
break
# Dynamic add/remove
sub = await xbbg.asubscribe(\["AAPL US Equity"], \["LAST\_PRICE"])
async for batch in sub:
if should\_add\_msft:
await sub.add(\["MSFT US Equity"])
if should\_remove\_aapl:
await sub.remove(\["AAPL US Equity"])
# Tick mode (dict conversion)
sub = await xbbg.asubscribe(\["AAPL US Equity"], \["LAST\_PRICE"], tick\_mode=True)
async for tick\_dict in sub:
print(tick\_dict) # {'ticker': 'AAPL US Equity', 'LAST\_PRICE': 150.25, ...}
#### astream
```python
async def astream(
tickers: str | list[str],
fields: str | list[str],
*,
raw: bool = False,
all_fields: bool = False,
backend: Backend | str | None = None,
callback: Callable[[pa.RecordBatch | nw.DataFrame | dict[str, Any]],
None] | None = None,
tick_mode: bool = False,
flush_threshold: int | None = None,
stream_capacity: int | None = None,
overflow_policy: str | None = None)
```
High-level async streaming - simple iteration.
This is the simple API for streaming data. For dynamic add/remove,
use asubscribe() instead.
**Arguments**:
* `tickers` - Securities to subscribe to
* `fields` - Fields to subscribe to
* `raw` - If True, yield raw Arrow RecordBatches
* `all_fields` - If True, expose all top-level scalar Bloomberg subscription fields
* `backend` - DataFrame backend for batch conversion
* `callback` - Optional callback function to invoke on each batch
* `tick_mode` - If True, convert batches to dicts
**Yields**:
Batches of market data (RecordBatch, DataFrame, or dict)
Example::
async for batch in xbbg.astream(\["AAPL US Equity"], \["LAST\_PRICE"]):
print(batch)
if done:
break
# With callback
def on\_batch(batch):
print(f"Got batch: {batch}")
async for \_ in xbbg.astream(\["AAPL US Equity"], \["LAST\_PRICE"], callback=on\_batch):
pass
#### stream
```python
def stream(tickers: str | list[str],
fields: str | list[str],
*,
raw: bool = False,
all_fields: bool = False,
backend: Backend | str | None = None,
callback: Callable[[pa.RecordBatch | nw.DataFrame | dict[str, Any]],
None] | None = None,
tick_mode: bool = False,
flush_threshold: int | None = None,
stream_capacity: int | None = None,
overflow_policy: str | None = None)
```
High-level sync streaming using a background thread.
Note: This is a generator that runs the async stream in a background
thread. Use astream() for async contexts.
**Arguments**:
* `tickers` - Securities to subscribe to
* `fields` - Fields to subscribe to
* `raw` - If True, yield raw Arrow RecordBatches
* `all_fields` - If True, expose all top-level scalar Bloomberg subscription fields
* `backend` - DataFrame backend for batch conversion
* `callback` - Optional callback function to invoke on each batch
* `tick_mode` - If True, convert batches to dicts
**Yields**:
Batches of market data
Example::
for batch in xbbg.stream(\["AAPL US Equity"], \["LAST\_PRICE"]):
print(batch)
if done:
break
#### avwap
```python
async def avwap(tickers: str | list[str],
fields: str | list[str] | None = None,
*,
start_time: str | None = None,
end_time: str | None = None,
raw: bool = False,
all_fields: bool = False,
backend: Backend | str | None = None) -> Subscription
```
Subscribe to real-time VWAP data (//blp/mktvwap).
Provides streaming Volume Weighted Average Price calculations.
**Arguments**:
* `tickers` - Securities to subscribe to
* `fields` - Fields to subscribe to (default: RT\_PX\_VWAP, RT\_VWAP\_VOLUME)
* `start_time` - VWAP calculation start time (e.g., "09:30")
* `end_time` - VWAP calculation end time (e.g., "16:00")
* `raw` - If True, yield raw Arrow RecordBatches for max performance
* `all_fields` - If True, expose all top-level scalar Bloomberg subscription fields
* `backend` - DataFrame backend for batch conversion (ignored if raw=True)
**Returns**:
Subscription handle for iteration and control
Example::
# Basic usage - subscribe to VWAP
sub = await xbbg.avwap(\["AAPL US Equity"])
async for batch in sub:
print(batch)
await sub.unsubscribe()
# With custom time window
sub = await xbbg.avwap(\["AAPL US Equity", "MSFT US Equity"], start\_time="09:30", end\_time="16:00")
# With specific fields
sub = await xbbg.avwap("AAPL US Equity", \["RT\_PX\_VWAP", "RT\_VWAP\_VOLUME", "RT\_VWAP\_TURNOVER"])
#### amktbar
```python
async def amktbar(tickers: str | list[str],
*,
interval: int = 1,
start_time: str | None = None,
end_time: str | None = None,
raw: bool = False,
all_fields: bool = False,
backend: Backend | str | None = None) -> Subscription
```
Subscribe to real-time streaming OHLC bars.
Like bdib but streaming instead of historical. Provides real-time
bar updates as they form during the trading day.
**Arguments**:
* `tickers` - Security identifier(s).
* `interval` - Bar interval in minutes (default: 1).
* `start_time` - Optional start time in HH:MM format.
* `end_time` - Optional end time in HH:MM format.
* `raw` - If True, return raw pyarrow RecordBatch (default: False).
* `all_fields` - If True, expose all top-level scalar Bloomberg subscription fields
* `backend` - DataFrame backend to return. If None, uses global default.
**Returns**:
Subscription object for async iteration.
Example::
# Subscribe to 5-minute bars
async with await amktbar("AAPL US Equity", interval=5) as sub:
async for batch in sub:
print(batch)
# Multiple securities
sub = await amktbar(\["AAPL US Equity", "MSFT US Equity"], interval=1)
async for batch in sub:
print(batch)
#### adepth
```python
async def adepth(tickers: str | list[str],
*,
raw: bool = False,
all_fields: bool = False,
backend: Backend | str | None = None) -> Subscription
```
Subscribe to Level 2 market depth / order book data.
.. warning::
**Requires Bloomberg B-PIPE license.** This feature is not available
with standard Terminal connections.
Provides real-time order book updates with bid/ask prices and sizes
at multiple levels.
**Arguments**:
* `tickers` - Security identifier(s).
* `raw` - If True, return raw pyarrow RecordBatch (default: False).
* `all_fields` - If True, expose all top-level scalar Bloomberg subscription fields
* `backend` - DataFrame backend to return. If None, uses global default.
**Returns**:
Subscription object for async iteration.
**Raises**:
* `BlpBPipeError` - If B-PIPE license is not available.
Example::
# Subscribe to market depth
async with await adepth("AAPL US Equity") as sub:
async for batch in sub:
print(batch) # Order book updates
#### achains
```python
async def achains(underlying: str,
*,
chain_type: str = "OPTIONS",
raw: bool = False,
all_fields: bool = False,
backend: Backend | str | None = None) -> Subscription
```
Subscribe to option or futures chain updates.
.. warning::
**Requires Bloomberg B-PIPE license.** This feature is not available
with standard Terminal connections.
Provides real-time updates for option chains or futures chains
on a given underlying security.
**Arguments**:
* `underlying` - Underlying security identifier.
* `chain_type` - Type of chain - "OPTIONS" or "FUTURES" (default: "OPTIONS").
* `raw` - If True, return raw pyarrow RecordBatch (default: False).
* `all_fields` - If True, expose all top-level scalar Bloomberg subscription fields
* `backend` - DataFrame backend to return. If None, uses global default.
**Returns**:
Subscription object for async iteration.
**Raises**:
* `BlpBPipeError` - If B-PIPE license is not available.
Example::
# Subscribe to option chain
async with await achains("AAPL US Equity") as sub:
async for batch in sub:
print(batch) # Option chain updates
# Subscribe to futures chain
sub = await achains("ES1 Index", chain\_type="FUTURES")
#### abta
```python
async def abta(tickers: str | list[str],
study: str,
*,
start_date: str | None = None,
end_date: str | None = None,
periodicity: str = "DAILY",
interval: int | None = None,
**study_params) -> DataFrameResult
```
Get technical analysis study data (async).
Uses Bloomberg //blp/tasvc service to calculate technical indicators.
**Arguments**:
* `tickers` - Security or list of securities
* `study` - Study type (e.g., 'sma', 'rsi', 'macd', 'boll', 'atr')
* `start_date` - Start date (YYYYMMDD format)
* `end_date` - End date (YYYYMMDD format)
* `periodicity` - Data periodicity ('DAILY', 'WEEKLY', 'MONTHLY', 'INTRADAY')
* `interval` - Intraday interval in minutes (only for periodicity='INTRADAY')
* `**study_params` - Study-specific parameters (e.g., period=20 for SMA period)
**Returns**:
DataFrame with study results
Available Studies:
Moving Averages: sma, ema, wma, vma, tma
* `Oscillators` - rsi, macd, mao, momentum, roc
* `Bands` - boll (Bollinger), keltner, mae
* `Trend` - dmi/adx, stoch, trender, parabolic/sar
* `Volume` - chko, ado, vat
* `Volatility` - atr, hurst
* `Other` - ichimoku, pivot, williams
Example::
# Simple Moving Average with 20-day period
df = await xbbg.abta("AAPL US Equity", "sma", period=20)
# RSI with 14-day period
df = await xbbg.abta("AAPL US Equity", "rsi", period=14)
# MACD with custom parameters
df = await xbbg.abta("AAPL US Equity", "macd", maPeriod1=12, maPeriod2=26, sigPeriod=9)
# Bollinger Bands with 20-day period and 2 std devs
df = await xbbg.abta("AAPL US Equity", "boll", period=20, upperBand=2.0, lowerBand=2.0)
# Intraday RSI with 60-minute bars
df = await xbbg.abta("AAPL US Equity", "rsi", periodicity="INTRADAY", interval=60)
# Multiple securities (sends concurrent requests)
df = await xbbg.abta(\["AAPL US Equity", "MSFT US Equity"], "rsi")
#### ta\_studies
```python
def ta_studies() -> list[str]
```
List available technical analysis study names.
**Returns**:
List of study short names that can be used with bta()/abta()
Example::
> > > xbbg.ta\_studies()
> > > \['sma', 'ema', 'rsi', 'macd', 'boll', 'atr', ...]
#### ta\_study\_params
```python
def ta_study_params(study: str) -> dict[str, Any]
```
Get default parameters for a technical analysis study.
**Arguments**:
* `study` - Study name (e.g., 'rsi', 'macd', 'boll')
**Returns**:
Dictionary of parameter names and their default values
Example::
> > > xbbg.ta\_study\_params('rsi')
* `{'period'` - 14, 'priceSourceClose': 'PX\_LAST'}
> > > xbbg.ta\_study\_params('macd')
* `{'maPeriod1'` - 12, 'maPeriod2': 26, 'sigPeriod': 9, 'priceSourceClose': 'PX\_LAST'}
> > > xbbg.ta\_study\_params('boll')
* `{'period'` - 20, 'upperBand': 2.0, 'lowerBand': 2.0, 'priceSourceClose': 'PX\_LAST'}
#### generate\_ta\_stubs
```python
def generate_ta_stubs(output_dir: str | None = None) -> str
```
Generate Python type stubs for technical analysis studies.
Creates a .pyi file with TypedDict definitions for all TA study parameters.
Stubs are generated from the //blp/tasvc schema for IDE autocomplete support.
**Arguments**:
* `output_dir` - Output directory (default: ~/.xbbg/stubs/)
**Returns**:
Path to the generated stub file.
Example::
> > > xbbg.generate\_ta\_stubs()
> > > '~/.xbbg/stubs/ta\_studies.pyi'
# Then in your code, IDE will autocomplete:
> > > from xbbg.stubs.ta\_studies import RSIParams
> > > params: RSIParams = {'period': 14}
#### abql
```python
async def abql(expression: str,
*,
backend: Backend | str | None = None) -> DataFrameResult
```
Async Bloomberg Query Language (BQL) request.
BQL is Bloomberg's powerful query language for financial analytics.
It allows you to query data across universes of securities with
complex filters, calculations, and time series operations.
**Arguments**:
* `expression` - BQL expression string.
* `backend` - DataFrame backend to return. If None, uses global default.
**Returns**:
DataFrame with columns: id, `field1`, `field2`, ...
Where 'id' is the security identifier from the BQL universe.
Example::
# Get price for a single security
df = await abql("get(px\_last) for('AAPL US Equity')")
# Get multiple fields
df = await abql("get(px\_last, volume) for('AAPL US Equity')")
# Holdings of an ETF
df = await abql("get(id\_isin, weights) for(holdings('SPY US Equity'))")
# Index members
df = await abql("get(px\_last) for(members('SPX Index'))")
# With filters
df = await abql("get(px\_last, pe\_ratio) for(members('SPX Index')) with(pe\_ratio > 20)")
# Time series
df = await abql("get(px\_last) for('AAPL US Equity') with(dates=range(-5d, 0d))")
#### absrch
```python
async def absrch(domain: str,
*,
backend: Backend | str | None = None,
**kwargs) -> DataFrameResult
```
Async Bloomberg Search (BSRCH) request.
BSRCH executes saved Bloomberg searches and returns matching securities.
**Arguments**:
* `domain` - The saved search domain/name (e.g., "FI:SOVR", "COMDTY:PRECIOUS").
* `backend` - DataFrame backend to return. If None, uses global default.
* `**kwargs` - Additional search parameters passed as request elements.
**Returns**:
DataFrame with columns from the saved search results.
Example::
# Sovereign bonds
df = await absrch("FI:SOVR")
# With additional parameters
df = await absrch("COMDTY:WEATHER", LOCATION="NYC", MODEL="GFS")
#### abqr
```python
async def abqr(ticker: str,
date_offset: str | None = None,
start_date: str | None = None,
end_date: str | None = None,
*,
event_types: Sequence[str] | None = None,
include_broker_codes: bool = False,
include_spread_price: bool = False,
include_yield: bool = False,
include_condition_codes: bool = False,
include_exchange_codes: bool = False,
backend: Backend | str | None = None,
**kwargs) -> DataFrameResult
```
Async Bloomberg Quote Request (BQR).
Retrieves dealer quote data using IntradayTickRequest with BID/ASK events.
Emulates the Excel =BQR() function.
**Arguments**:
* `ticker` - Security identifier. Supports Bloomberg tickers with pricing
source qualifiers (e.g., 'IBM US Equity@MSG1', '/isin/US037833FB15@MSG1').
* `date_offset` - Date offset from now (e.g., '-2d', '-1w', '-3h').
Mutually exclusive with start\_date/end\_date.
* `start_date` - Start date (e.g., '2024-01-15'). Defaults to 2 days ago.
* `end_date` - End date (e.g., '2024-01-17'). Defaults to today.
* `event_types` - Event types to retrieve. Defaults to \['BID', 'ASK'].
* `include_broker_codes` - Include broker/dealer codes (default False).
* `include_spread_price` - Include spread price for bonds (default False).
* `include_yield` - Include yield data for bonds (default False).
* `include_condition_codes` - Include trade condition codes (default False).
* `include_exchange_codes` - Include exchange codes (default False).
* `backend` - DataFrame backend to return. If None, uses global default.
* `**kwargs` - Additional options.
**Returns**:
DataFrame with columns: ticker, time, type, value, size,
plus optional brokerBuyCode, brokerSellCode, spreadPrice, etc.
Example::
# With date offset (like Excel BQR)
df = await abqr("IBM US Equity@MSG1", date\_offset="-2d")
# Bond with broker codes and spread
df = await abqr(
"US037833FB15@MSG1 Corp",
date\_offset="-2d",
include\_broker\_codes=True,
include\_spread\_price=True,
)
# With explicit date range
df = await abqr(
"XYZ 4.5 01/15/30@MSG1 Corp",
start\_date="2024-01-15",
end\_date="2024-01-17",
)
# Trade events only
df = await abqr(
"XYZ 4.5 01/15/30@MSG1 Corp",
date\_offset="-1d",
event\_types=\["TRADE"],
)
#### abflds
```python
async def abflds(fields: str | list[str] | None = None,
*,
search_spec: str | None = None,
backend: Backend | str | None = None,
**kwargs) -> DataFrameResult
```
Async Bloomberg field metadata lookup (BFLDS).
Unified field function: get metadata for specific fields, or search by keyword.
**Arguments**:
* `fields` - Single field or list of fields to get metadata for.
Mutually exclusive with search\_spec.
* `search_spec` - Search term to find fields by name/description.
Mutually exclusive with fields.
* `backend` - DataFrame backend to return. If None, uses global default.
* `**kwargs` - Infrastructure options (e.g., port, server).
**Returns**:
DataFrame with field information or search results.
**Raises**:
* `ValueError` - If neither fields nor search\_spec is provided, or both are provided.
Example::
# Get info for specific fields
df = await abflds(fields=\["PX\_LAST", "VOLUME"])
# Search for fields by keyword
df = await abflds(search\_spec="vwap")
#### abeqs
```python
async def abeqs(screen: str,
*,
asof: str | None = None,
screen_type: str = "PRIVATE",
group: str = "General",
backend: Backend | str | None = None,
**kwargs) -> DataFrameResult
```
Async Bloomberg Equity Screening (BEQS) request.
Execute a saved Bloomberg equity screen and return matching securities.
**Arguments**:
* `screen` - Screen name as saved in Bloomberg.
* `asof` - As-of date for the screen (YYYYMMDD format).
* `screen_type` - Screen type - "PRIVATE" (custom) or "GLOBAL" (Bloomberg).
* `group` - Group name if screen is organized into groups.
* `backend` - DataFrame backend to return. If None, uses global default.
* `**kwargs` - Additional request parameters.
**Returns**:
DataFrame with columns from the screen results (security, fieldData, etc.).
Example::
# Run a private screen
df = await abeqs("MyScreen")
# Run with as-of date
df = await abeqs("MyScreen", asof="20240101")
# Run a Bloomberg global screen
df = await abeqs("TOP\_DECL\_DVD", screen\_type="GLOBAL")
#### ablkp
```python
async def ablkp(query: str,
*,
yellowkey: str = "YK_FILTER_NONE",
language: str = "LANG_OVERRIDE_NONE",
max_results: int = 20,
backend: Backend | str | None = None,
**kwargs) -> DataFrameResult
```
Async Bloomberg security lookup (BLKP) request.
Search for securities by company name or partial ticker.
**Arguments**:
* `query` - Search query (company name or partial ticker).
* `yellowkey` - Asset class filter. Common values:
* "YK\_FILTER\_NONE" (default, all asset classes)
* "YK\_FILTER\_EQTY" (equities only)
* "YK\_FILTER\_CORP" (corporate bonds)
* "YK\_FILTER\_GOVT" (government bonds)
* "YK\_FILTER\_INDX" (indices)
* "YK\_FILTER\_CURR" (currencies)
* "YK\_FILTER\_CMDT" (commodities)
* `language` - Language override for results.
* `max_results` - Maximum number of results (default: 20, max: 1000).
* `backend` - DataFrame backend to return. If None, uses global default.
* `**kwargs` - Additional request parameters.
**Returns**:
DataFrame with columns: security, description, and other result fields.
Example::
# Search for Apple
df = await ablkp("Apple")
# Search for equities only
df = await ablkp("NVDA", yellowkey="YK\_FILTER\_EQTY")
# Get more results
df = await ablkp("Microsoft", max\_results=50)
#### abport
```python
async def abport(portfolio: str,
fields: str | Sequence[str],
*,
backend: Backend | str | None = None,
**kwargs) -> DataFrameResult
```
Async Bloomberg portfolio data (BPORT) request.
Get portfolio holdings and related data using PortfolioDataRequest.
**Arguments**:
* `portfolio` - Bloomberg PortfolioDataRequest security/portfolio ID string, not the PORT display name
(for example, `UXXXXXXX-X Client` from PRTU/PORT).
* `fields` - Field name or list of fields (e.g., "PORTFOLIO\_MWEIGHT").
* `backend` - DataFrame backend to return. If None, uses global default.
* `**kwargs` - Additional request parameters/overrides.
**Returns**:
DataFrame with portfolio data.
Example::
# Get portfolio overview data. Use the Bloomberg portfolio ID/security
# string, not the human-readable PORT display name.
df = await abport("UXXXXXXX-X Client", "PORTFOLIO\_DATA")
# Get portfolio weights
df = await abport("UXXXXXXX-X Client", "PORTFOLIO\_MWEIGHT")
#### abcurves
```python
async def abcurves(*,
country: str | None = None,
currency: str | None = None,
curve_type: str | None = None,
subtype: str | None = None,
curveid: str | None = None,
bbgid: str | None = None,
backend: Backend | str | None = None,
**kwargs) -> DataFrameResult
```
Async Bloomberg yield curve list (BCURVES) request.
Search for yield curves by country, currency, type, or other filters.
**Arguments**:
* `country` - Country code filter (e.g., "US", "GB", "DE").
* `currency` - Currency code filter (e.g., "USD", "EUR", "GBP").
* `curve_type` - Curve type filter (e.g., "GOVERNMENT", "CORPORATE").
* `subtype` - Curve subtype filter.
* `curveid` - Specific curve ID to look up.
* `bbgid` - Bloomberg Global ID filter.
* `backend` - DataFrame backend to return. If None, uses global default.
* `**kwargs` - Additional request parameters.
**Returns**:
DataFrame with yield curve information.
Example::
# List US yield curves
df = await abcurves(country="US")
# List USD government curves
df = await abcurves(currency="USD", curve\_type="GOVERNMENT")
# Look up specific curve
df = await abcurves(curveid="YCSW0023 Index")
#### abgovts
```python
async def abgovts(query: str | None = None,
*,
partial_match: bool = True,
backend: Backend | str | None = None,
**kwargs) -> DataFrameResult
```
Async Bloomberg government securities list (BGOVTS) request.
Search for government securities by ticker or name.
**Arguments**:
* `query` - Search query (ticker or partial name).
* `partial_match` - If True, match partial ticker names (default: True).
* `backend` - DataFrame backend to return. If None, uses global default.
* `**kwargs` - Additional request parameters.
**Returns**:
DataFrame with government securities information.
Example::
# Search for US Treasury securities
df = await abgovts("T")
# Search for German government bonds
df = await abgovts("DBR")
# Exact match only
df = await abgovts("T 2.5 05/15/24", partial\_match=False)
#### afieldInfo
```python
async def afieldInfo(fields: str | list[str],
*,
backend: Backend | str | None = None,
**kwargs) -> DataFrameResult
```
Get metadata about Bloomberg fields (async).
Convenience wrapper around abflds(fields=...).
**Arguments**:
* `fields` - Single field or list of fields to get metadata for.
* `backend` - DataFrame backend to return. If None, uses global default.
* `**kwargs` - Infrastructure options.
**Returns**:
DataFrame with field information.
Example::
df = await afieldInfo(\["PX\_LAST", "VOLUME"])
#### afieldSearch
```python
async def afieldSearch(searchterm: str,
*,
backend: Backend | str | None = None,
**kwargs) -> DataFrameResult
```
Search for Bloomberg fields by keyword (async).
Convenience wrapper around abflds(search\_spec=...).
**Arguments**:
* `searchterm` - Search term to find fields by name/description.
* `backend` - DataFrame backend to return. If None, uses global default.
* `**kwargs` - Infrastructure options.
**Returns**:
DataFrame with search results.
Example::
df = await afieldSearch("vwap")
#### abops
```python
async def abops(service: str | Service = Service.REFDATA) -> list[str]
```
List available operations for a Bloomberg service (async).
**Arguments**:
* `service` - Service URI or Service enum (default: //blp/refdata)
**Returns**:
List of operation names.
Example::
> > > ops = await abops()
> > > print(ops)
> > > \['ReferenceDataRequest', 'HistoricalDataRequest', ...]
> > > ops = await abops("//blp/instruments")
> > > print(ops)
> > > \['InstrumentListRequest', ...]
#### abschema
```python
async def abschema(service: str | Service = Service.REFDATA,
operation: str | Operation | None = None) -> dict
```
Get Bloomberg service or operation schema (async).
Returns introspected schema with element definitions, types, and enum values.
Schemas are cached locally (~/.xbbg/schemas/) for fast subsequent access.
**Arguments**:
* `service` - Service URI or Service enum (default: //blp/refdata)
* `operation` - Optional operation name. If None, returns full service schema.
**Returns**:
Dictionary with schema information:
* If operation is None: Full service schema with all operations
* If operation is specified: Just that operation's request/response schema
Example::
> > > # Get full service schema
> > >
> > > schema = await abschema()
> > > print(schema\['operations']\[0]\['name'])
> > > 'ReferenceDataRequest'
> > > # Get specific operation schema
> > >
> > > op\_schema = await abschema(operation="ReferenceDataRequest")
> > > print(op\_schema\['request']\['children']\[0]\['name'])
> > > 'securities'
> > > # Get enum values for an element
> > >
> > > op = await abschema(operation="HistoricalDataRequest")
> > > for child in op\['request']\['children']:
> > > ... if child.get('enum\_values'):
> > > ... print(f"{child\['name']}: {child\['enum\_values']}")
---
---
url: 'https://xbbg.org/javascript/api/core/variables/blp.md'
---
> `const` **blp**: [`BlpNamespace`](/javascript/api/core/interfaces/blpnamespace/)
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:788`)
---
---
url: 'https://xbbg.org/javascript/api/core/classes/blperror.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:168`)
## Extends
* `Error`
## Extended by
* [`BlpSessionError`](/javascript/api/core/classes/blpsessionerror/)
* [`BlpRequestError`](/javascript/api/core/classes/blprequesterror/)
* [`BlpValidationError`](/javascript/api/core/classes/blpvalidationerror/)
* [`BlpTimeoutError`](/javascript/api/core/classes/blptimeouterror/)
* [`BlpInternalError`](/javascript/api/core/classes/blpinternalerror/)
## Constructors
### Constructor
> **new BlpError**(`message?`): `BlpError`
Defined in: docs/node\_modules/typescript/lib/lib.es5.d.ts:1082
#### Parameters
##### message?
`string`
#### Returns
`BlpError`
#### Inherited from
`Error.constructor`
### Constructor
> **new BlpError**(`message?`, `options?`): `BlpError`
Defined in: docs/node\_modules/typescript/lib/lib.es5.d.ts:1082
#### Parameters
##### message?
`string`
##### options?
`ErrorOptions`
#### Returns
`BlpError`
#### Inherited from
`Error.constructor`
## Properties
### cause?
> `optional` **cause?**: `unknown`
Defined in: docs/node\_modules/typescript/lib/lib.es2022.error.d.ts:26
#### Inherited from
`Error.cause`
***
### message
> **message**: `string`
Defined in: docs/node\_modules/typescript/lib/lib.es5.d.ts:1077
#### Inherited from
`Error.message`
***
### name
> `readonly` **name**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:169`)
#### Overrides
`Error.name`
***
### stack?
> `optional` **stack?**: `string`
Defined in: docs/node\_modules/typescript/lib/lib.es5.d.ts:1078
#### Inherited from
`Error.stack`
***
### stackTraceLimit
> `static` **stackTraceLimit**: `number`
Defined in: docs/node\_modules/@types/node/globals.d.ts:68
The `Error.stackTraceLimit` property specifies the number of stack frames
collected by a stack trace (whether generated by `new Error().stack` or
`Error.captureStackTrace(obj)`).
The default value is `10` but may be set to any valid JavaScript number. Changes
will affect any stack trace captured *after* the value has been changed.
If set to a non-number value, or set to a negative number, stack traces will
not capture any frames.
#### Inherited from
`Error.stackTraceLimit`
## Methods
### captureStackTrace()
> `static` **captureStackTrace**(`targetObject`, `constructorOpt?`): `void`
Defined in: docs/node\_modules/@types/node/globals.d.ts:52
Creates a `.stack` property on `targetObject`, which when accessed returns
a string representing the location in the code at which
`Error.captureStackTrace()` was called.
```js
const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack; // Similar to `new Error().stack`
```
The first line of the trace will be prefixed with
`${myObject.name}: ${myObject.message}`.
The optional `constructorOpt` argument accepts a function. If given, all frames
above `constructorOpt`, including `constructorOpt`, will be omitted from the
generated stack trace.
The `constructorOpt` argument is useful for hiding implementation
details of error generation from the user. For instance:
```js
function a() {
b();
}
function b() {
c();
}
function c() {
// Create an error without stack trace to avoid calculating the stack trace twice.
const { stackTraceLimit } = Error;
Error.stackTraceLimit = 0;
const error = new Error();
Error.stackTraceLimit = stackTraceLimit;
// Capture the stack trace above function b
Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
throw error;
}
a();
```
#### Parameters
##### targetObject
`object`
##### constructorOpt?
`Function`
#### Returns
`void`
#### Inherited from
`Error.captureStackTrace`
***
### prepareStackTrace()
> `static` **prepareStackTrace**(`err`, `stackTraces`): `any`
Defined in: docs/node\_modules/@types/node/globals.d.ts:56
#### Parameters
##### err
`Error`
##### stackTraces
`CallSite`\[]
#### Returns
`any`
#### See
https://v8.dev/docs/stack-trace-api#customizing-stack-traces
#### Inherited from
`Error.prepareStackTrace`
---
---
url: 'https://xbbg.org/javascript/api/core/classes/blpinternalerror.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:183`)
## Extends
* [`BlpError`](/javascript/api/core/classes/blperror/)
## Constructors
### Constructor
> **new BlpInternalError**(`message?`): `BlpInternalError`
Defined in: docs/node\_modules/typescript/lib/lib.es5.d.ts:1082
#### Parameters
##### message?
`string`
#### Returns
`BlpInternalError`
#### Inherited from
[`BlpError`](/javascript/api/core/classes/blperror/).[`constructor`](/javascript/api/core/classes/blperror/#constructor)
### Constructor
> **new BlpInternalError**(`message?`, `options?`): `BlpInternalError`
Defined in: docs/node\_modules/typescript/lib/lib.es5.d.ts:1082
#### Parameters
##### message?
`string`
##### options?
`ErrorOptions`
#### Returns
`BlpInternalError`
#### Inherited from
[`BlpError`](/javascript/api/core/classes/blperror/).[`constructor`](/javascript/api/core/classes/blperror/#constructor)
## Properties
### cause?
> `optional` **cause?**: `unknown`
Defined in: docs/node\_modules/typescript/lib/lib.es2022.error.d.ts:26
#### Inherited from
[`BlpError`](/javascript/api/core/classes/blperror/).[`cause`](/javascript/api/core/classes/blperror/#cause)
***
### message
> **message**: `string`
Defined in: docs/node\_modules/typescript/lib/lib.es5.d.ts:1077
#### Inherited from
[`BlpError`](/javascript/api/core/classes/blperror/).[`message`](/javascript/api/core/classes/blperror/#message)
***
### name
> `readonly` **name**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:169`)
#### Inherited from
[`BlpError`](/javascript/api/core/classes/blperror/).[`name`](/javascript/api/core/classes/blperror/#name)
***
### stack?
> `optional` **stack?**: `string`
Defined in: docs/node\_modules/typescript/lib/lib.es5.d.ts:1078
#### Inherited from
[`BlpError`](/javascript/api/core/classes/blperror/).[`stack`](/javascript/api/core/classes/blperror/#stack)
***
### stackTraceLimit
> `static` **stackTraceLimit**: `number`
Defined in: docs/node\_modules/@types/node/globals.d.ts:68
The `Error.stackTraceLimit` property specifies the number of stack frames
collected by a stack trace (whether generated by `new Error().stack` or
`Error.captureStackTrace(obj)`).
The default value is `10` but may be set to any valid JavaScript number. Changes
will affect any stack trace captured *after* the value has been changed.
If set to a non-number value, or set to a negative number, stack traces will
not capture any frames.
#### Inherited from
[`BlpError`](/javascript/api/core/classes/blperror/).[`stackTraceLimit`](/javascript/api/core/classes/blperror/#stacktracelimit)
## Methods
### captureStackTrace()
> `static` **captureStackTrace**(`targetObject`, `constructorOpt?`): `void`
Defined in: docs/node\_modules/@types/node/globals.d.ts:52
Creates a `.stack` property on `targetObject`, which when accessed returns
a string representing the location in the code at which
`Error.captureStackTrace()` was called.
```js
const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack; // Similar to `new Error().stack`
```
The first line of the trace will be prefixed with
`${myObject.name}: ${myObject.message}`.
The optional `constructorOpt` argument accepts a function. If given, all frames
above `constructorOpt`, including `constructorOpt`, will be omitted from the
generated stack trace.
The `constructorOpt` argument is useful for hiding implementation
details of error generation from the user. For instance:
```js
function a() {
b();
}
function b() {
c();
}
function c() {
// Create an error without stack trace to avoid calculating the stack trace twice.
const { stackTraceLimit } = Error;
Error.stackTraceLimit = 0;
const error = new Error();
Error.stackTraceLimit = stackTraceLimit;
// Capture the stack trace above function b
Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
throw error;
}
a();
```
#### Parameters
##### targetObject
`object`
##### constructorOpt?
`Function`
#### Returns
`void`
#### Inherited from
[`BlpError`](/javascript/api/core/classes/blperror/).[`captureStackTrace`](/javascript/api/core/classes/blperror/#capturestacktrace)
***
### prepareStackTrace()
> `static` **prepareStackTrace**(`err`, `stackTraces`): `any`
Defined in: docs/node\_modules/@types/node/globals.d.ts:56
#### Parameters
##### err
`Error`
##### stackTraces
`CallSite`\[]
#### Returns
`any`
#### See
https://v8.dev/docs/stack-trace-api#customizing-stack-traces
#### Inherited from
[`BlpError`](/javascript/api/core/classes/blperror/).[`prepareStackTrace`](/javascript/api/core/classes/blperror/#preparestacktrace)
---
---
url: 'https://xbbg.org/javascript/api/core/interfaces/blpnamespace.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:462`)
## Methods
### abdh()
> **abdh**(`tickers`, `fields`, `start?`, `end?`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:489`)
#### Parameters
##### tickers
`string` | `string`\[]
##### fields
`string` | `string`\[]
##### start?
`string`
##### end?
`string`
##### options?
[`BdhOptions`](/javascript/api/core/interfaces/bdhoptions/)
#### Returns
`Promise`<`Table`<`any`>>
***
### abdib()
> **abdib**(`ticker`, `dt?`, `interval?`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:502`)
#### Parameters
##### ticker
`string`
##### dt?
`string`
##### interval?
`number`
##### options?
[`BdibOptions`](/javascript/api/core/interfaces/bdiboptions/)
#### Returns
`Promise`<`Table`<`any`>>
***
### abdp()
> **abdp**(`tickers`, `fields`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:484`)
#### Parameters
##### tickers
`string` | `string`\[]
##### fields
`string` | `string`\[]
##### options?
[`BdpOptions`](/javascript/api/core/interfaces/bdpoptions/)
#### Returns
`Promise`<`Table`<`any`>>
***
### abds()
> **abds**(`tickers`, `fields`, `overrides?`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:496`)
#### Parameters
##### tickers
`string` | `string`\[]
##### fields
`string` | `string`\[]
##### overrides?
`Record`<`string`, `string` | `number` | `boolean`>
##### options?
[`BdpOptions`](/javascript/api/core/interfaces/bdpoptions/)
#### Returns
`Promise`<`Table`<`any`>>
***
### abdtick()
> **abdtick**(`ticker`, `start`, `end`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:508`)
#### Parameters
##### ticker
`string`
##### start
`string`
##### end
`string`
##### options?
[`BdtickOptions`](/javascript/api/core/interfaces/bdtickoptions/)
#### Returns
`Promise`<`Table`<`any`>>
***
### asubscribe()
> **asubscribe**(`tickers`, `fields`): `Promise`<[`Subscription`](/javascript/api/core/classes/subscription/)>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:514`)
#### Parameters
##### tickers
`string` | `string`\[]
##### fields
`string` | `string`\[]
#### Returns
`Promise`<[`Subscription`](/javascript/api/core/classes/subscription/)>
***
### bdh()
> **bdh**(`tickers`, `fields`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:468`)
#### Parameters
##### tickers
`string` | `string`\[]
##### fields
`string` | `string`\[]
##### options?
[`BdhOptions`](/javascript/api/core/interfaces/bdhoptions/)
#### Returns
`Promise`<`Table`<`any`>>
***
### bdib()
> **bdib**(`ticker`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:478`)
#### Parameters
##### ticker
`string`
##### options?
[`BdibOptions`](/javascript/api/core/interfaces/bdiboptions/)
#### Returns
`Promise`<`Table`<`any`>>
***
### bdp()
> **bdp**(`tickers`, `fields`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:463`)
#### Parameters
##### tickers
`string` | `string`\[]
##### fields
`string` | `string`\[]
##### options?
[`BdpOptions`](/javascript/api/core/interfaces/bdpoptions/)
#### Returns
`Promise`<`Table`<`any`>>
***
### bds()
> **bds**(`tickers`, `fields`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:473`)
#### Parameters
##### tickers
`string` | `string`\[]
##### fields
`string` | `string`\[]
##### options?
[`BdpOptions`](/javascript/api/core/interfaces/bdpoptions/)
#### Returns
`Promise`<`Table`<`any`>>
***
### bdtick()
> **bdtick**(`ticker`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:479`)
#### Parameters
##### ticker
`string`
##### options?
[`BdtickOptions`](/javascript/api/core/interfaces/bdtickoptions/)
#### Returns
`Promise`<`Table`<`any`>>
***
### subscribe()
> **subscribe**(`tickers`, `fields`): `Promise`<[`Subscription`](/javascript/api/core/classes/subscription/)>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:480`)
#### Parameters
##### tickers
`string` | `string`\[]
##### fields
`string` | `string`\[]
#### Returns
`Promise`<[`Subscription`](/javascript/api/core/classes/subscription/)>
---
---
url: 'https://xbbg.org/javascript/api/core/classes/blprequesterror.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:172`)
## Extends
* [`BlpError`](/javascript/api/core/classes/blperror/)
## Constructors
### Constructor
> **new BlpRequestError**(`message?`): `BlpRequestError`
Defined in: docs/node\_modules/typescript/lib/lib.es5.d.ts:1082
#### Parameters
##### message?
`string`
#### Returns
`BlpRequestError`
#### Inherited from
[`BlpError`](/javascript/api/core/classes/blperror/).[`constructor`](/javascript/api/core/classes/blperror/#constructor)
### Constructor
> **new BlpRequestError**(`message?`, `options?`): `BlpRequestError`
Defined in: docs/node\_modules/typescript/lib/lib.es5.d.ts:1082
#### Parameters
##### message?
`string`
##### options?
`ErrorOptions`
#### Returns
`BlpRequestError`
#### Inherited from
[`BlpError`](/javascript/api/core/classes/blperror/).[`constructor`](/javascript/api/core/classes/blperror/#constructor)
## Properties
### cause?
> `optional` **cause?**: `unknown`
Defined in: docs/node\_modules/typescript/lib/lib.es2022.error.d.ts:26
#### Inherited from
[`BlpError`](/javascript/api/core/classes/blperror/).[`cause`](/javascript/api/core/classes/blperror/#cause)
***
### code?
> `readonly` `optional` **code?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:176`)
***
### message
> **message**: `string`
Defined in: docs/node\_modules/typescript/lib/lib.es5.d.ts:1077
#### Inherited from
[`BlpError`](/javascript/api/core/classes/blperror/).[`message`](/javascript/api/core/classes/blperror/#message)
***
### name
> `readonly` **name**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:169`)
#### Inherited from
[`BlpError`](/javascript/api/core/classes/blperror/).[`name`](/javascript/api/core/classes/blperror/#name)
***
### operation?
> `readonly` `optional` **operation?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:174`)
***
### request\_id?
> `readonly` `optional` **request\_id?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:175`)
***
### service?
> `readonly` `optional` **service?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:173`)
***
### stack?
> `optional` **stack?**: `string`
Defined in: docs/node\_modules/typescript/lib/lib.es5.d.ts:1078
#### Inherited from
[`BlpError`](/javascript/api/core/classes/blperror/).[`stack`](/javascript/api/core/classes/blperror/#stack)
***
### stackTraceLimit
> `static` **stackTraceLimit**: `number`
Defined in: docs/node\_modules/@types/node/globals.d.ts:68
The `Error.stackTraceLimit` property specifies the number of stack frames
collected by a stack trace (whether generated by `new Error().stack` or
`Error.captureStackTrace(obj)`).
The default value is `10` but may be set to any valid JavaScript number. Changes
will affect any stack trace captured *after* the value has been changed.
If set to a non-number value, or set to a negative number, stack traces will
not capture any frames.
#### Inherited from
[`BlpError`](/javascript/api/core/classes/blperror/).[`stackTraceLimit`](/javascript/api/core/classes/blperror/#stacktracelimit)
## Methods
### captureStackTrace()
> `static` **captureStackTrace**(`targetObject`, `constructorOpt?`): `void`
Defined in: docs/node\_modules/@types/node/globals.d.ts:52
Creates a `.stack` property on `targetObject`, which when accessed returns
a string representing the location in the code at which
`Error.captureStackTrace()` was called.
```js
const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack; // Similar to `new Error().stack`
```
The first line of the trace will be prefixed with
`${myObject.name}: ${myObject.message}`.
The optional `constructorOpt` argument accepts a function. If given, all frames
above `constructorOpt`, including `constructorOpt`, will be omitted from the
generated stack trace.
The `constructorOpt` argument is useful for hiding implementation
details of error generation from the user. For instance:
```js
function a() {
b();
}
function b() {
c();
}
function c() {
// Create an error without stack trace to avoid calculating the stack trace twice.
const { stackTraceLimit } = Error;
Error.stackTraceLimit = 0;
const error = new Error();
Error.stackTraceLimit = stackTraceLimit;
// Capture the stack trace above function b
Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
throw error;
}
a();
```
#### Parameters
##### targetObject
`object`
##### constructorOpt?
`Function`
#### Returns
`void`
#### Inherited from
[`BlpError`](/javascript/api/core/classes/blperror/).[`captureStackTrace`](/javascript/api/core/classes/blperror/#capturestacktrace)
***
### prepareStackTrace()
> `static` **prepareStackTrace**(`err`, `stackTraces`): `any`
Defined in: docs/node\_modules/@types/node/globals.d.ts:56
#### Parameters
##### err
`Error`
##### stackTraces
`CallSite`\[]
#### Returns
`any`
#### See
https://v8.dev/docs/stack-trace-api#customizing-stack-traces
#### Inherited from
[`BlpError`](/javascript/api/core/classes/blperror/).[`prepareStackTrace`](/javascript/api/core/classes/blperror/#preparestacktrace)
---
---
url: 'https://xbbg.org/javascript/api/core/classes/blpsessionerror.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:171`)
## Extends
* [`BlpError`](/javascript/api/core/classes/blperror/)
## Constructors
### Constructor
> **new BlpSessionError**(`message?`): `BlpSessionError`
Defined in: docs/node\_modules/typescript/lib/lib.es5.d.ts:1082
#### Parameters
##### message?
`string`
#### Returns
`BlpSessionError`
#### Inherited from
[`BlpError`](/javascript/api/core/classes/blperror/).[`constructor`](/javascript/api/core/classes/blperror/#constructor)
### Constructor
> **new BlpSessionError**(`message?`, `options?`): `BlpSessionError`
Defined in: docs/node\_modules/typescript/lib/lib.es5.d.ts:1082
#### Parameters
##### message?
`string`
##### options?
`ErrorOptions`
#### Returns
`BlpSessionError`
#### Inherited from
[`BlpError`](/javascript/api/core/classes/blperror/).[`constructor`](/javascript/api/core/classes/blperror/#constructor)
## Properties
### cause?
> `optional` **cause?**: `unknown`
Defined in: docs/node\_modules/typescript/lib/lib.es2022.error.d.ts:26
#### Inherited from
[`BlpError`](/javascript/api/core/classes/blperror/).[`cause`](/javascript/api/core/classes/blperror/#cause)
***
### message
> **message**: `string`
Defined in: docs/node\_modules/typescript/lib/lib.es5.d.ts:1077
#### Inherited from
[`BlpError`](/javascript/api/core/classes/blperror/).[`message`](/javascript/api/core/classes/blperror/#message)
***
### name
> `readonly` **name**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:169`)
#### Inherited from
[`BlpError`](/javascript/api/core/classes/blperror/).[`name`](/javascript/api/core/classes/blperror/#name)
***
### stack?
> `optional` **stack?**: `string`
Defined in: docs/node\_modules/typescript/lib/lib.es5.d.ts:1078
#### Inherited from
[`BlpError`](/javascript/api/core/classes/blperror/).[`stack`](/javascript/api/core/classes/blperror/#stack)
***
### stackTraceLimit
> `static` **stackTraceLimit**: `number`
Defined in: docs/node\_modules/@types/node/globals.d.ts:68
The `Error.stackTraceLimit` property specifies the number of stack frames
collected by a stack trace (whether generated by `new Error().stack` or
`Error.captureStackTrace(obj)`).
The default value is `10` but may be set to any valid JavaScript number. Changes
will affect any stack trace captured *after* the value has been changed.
If set to a non-number value, or set to a negative number, stack traces will
not capture any frames.
#### Inherited from
[`BlpError`](/javascript/api/core/classes/blperror/).[`stackTraceLimit`](/javascript/api/core/classes/blperror/#stacktracelimit)
## Methods
### captureStackTrace()
> `static` **captureStackTrace**(`targetObject`, `constructorOpt?`): `void`
Defined in: docs/node\_modules/@types/node/globals.d.ts:52
Creates a `.stack` property on `targetObject`, which when accessed returns
a string representing the location in the code at which
`Error.captureStackTrace()` was called.
```js
const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack; // Similar to `new Error().stack`
```
The first line of the trace will be prefixed with
`${myObject.name}: ${myObject.message}`.
The optional `constructorOpt` argument accepts a function. If given, all frames
above `constructorOpt`, including `constructorOpt`, will be omitted from the
generated stack trace.
The `constructorOpt` argument is useful for hiding implementation
details of error generation from the user. For instance:
```js
function a() {
b();
}
function b() {
c();
}
function c() {
// Create an error without stack trace to avoid calculating the stack trace twice.
const { stackTraceLimit } = Error;
Error.stackTraceLimit = 0;
const error = new Error();
Error.stackTraceLimit = stackTraceLimit;
// Capture the stack trace above function b
Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
throw error;
}
a();
```
#### Parameters
##### targetObject
`object`
##### constructorOpt?
`Function`
#### Returns
`void`
#### Inherited from
[`BlpError`](/javascript/api/core/classes/blperror/).[`captureStackTrace`](/javascript/api/core/classes/blperror/#capturestacktrace)
***
### prepareStackTrace()
> `static` **prepareStackTrace**(`err`, `stackTraces`): `any`
Defined in: docs/node\_modules/@types/node/globals.d.ts:56
#### Parameters
##### err
`Error`
##### stackTraces
`CallSite`\[]
#### Returns
`any`
#### See
https://v8.dev/docs/stack-trace-api#customizing-stack-traces
#### Inherited from
[`BlpError`](/javascript/api/core/classes/blperror/).[`prepareStackTrace`](/javascript/api/core/classes/blperror/#preparestacktrace)
---
---
url: 'https://xbbg.org/javascript/api/core/classes/blptimeouterror.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:182`)
## Extends
* [`BlpError`](/javascript/api/core/classes/blperror/)
## Constructors
### Constructor
> **new BlpTimeoutError**(`message?`): `BlpTimeoutError`
Defined in: docs/node\_modules/typescript/lib/lib.es5.d.ts:1082
#### Parameters
##### message?
`string`
#### Returns
`BlpTimeoutError`
#### Inherited from
[`BlpError`](/javascript/api/core/classes/blperror/).[`constructor`](/javascript/api/core/classes/blperror/#constructor)
### Constructor
> **new BlpTimeoutError**(`message?`, `options?`): `BlpTimeoutError`
Defined in: docs/node\_modules/typescript/lib/lib.es5.d.ts:1082
#### Parameters
##### message?
`string`
##### options?
`ErrorOptions`
#### Returns
`BlpTimeoutError`
#### Inherited from
[`BlpError`](/javascript/api/core/classes/blperror/).[`constructor`](/javascript/api/core/classes/blperror/#constructor)
## Properties
### cause?
> `optional` **cause?**: `unknown`
Defined in: docs/node\_modules/typescript/lib/lib.es2022.error.d.ts:26
#### Inherited from
[`BlpError`](/javascript/api/core/classes/blperror/).[`cause`](/javascript/api/core/classes/blperror/#cause)
***
### message
> **message**: `string`
Defined in: docs/node\_modules/typescript/lib/lib.es5.d.ts:1077
#### Inherited from
[`BlpError`](/javascript/api/core/classes/blperror/).[`message`](/javascript/api/core/classes/blperror/#message)
***
### name
> `readonly` **name**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:169`)
#### Inherited from
[`BlpError`](/javascript/api/core/classes/blperror/).[`name`](/javascript/api/core/classes/blperror/#name)
***
### stack?
> `optional` **stack?**: `string`
Defined in: docs/node\_modules/typescript/lib/lib.es5.d.ts:1078
#### Inherited from
[`BlpError`](/javascript/api/core/classes/blperror/).[`stack`](/javascript/api/core/classes/blperror/#stack)
***
### stackTraceLimit
> `static` **stackTraceLimit**: `number`
Defined in: docs/node\_modules/@types/node/globals.d.ts:68
The `Error.stackTraceLimit` property specifies the number of stack frames
collected by a stack trace (whether generated by `new Error().stack` or
`Error.captureStackTrace(obj)`).
The default value is `10` but may be set to any valid JavaScript number. Changes
will affect any stack trace captured *after* the value has been changed.
If set to a non-number value, or set to a negative number, stack traces will
not capture any frames.
#### Inherited from
[`BlpError`](/javascript/api/core/classes/blperror/).[`stackTraceLimit`](/javascript/api/core/classes/blperror/#stacktracelimit)
## Methods
### captureStackTrace()
> `static` **captureStackTrace**(`targetObject`, `constructorOpt?`): `void`
Defined in: docs/node\_modules/@types/node/globals.d.ts:52
Creates a `.stack` property on `targetObject`, which when accessed returns
a string representing the location in the code at which
`Error.captureStackTrace()` was called.
```js
const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack; // Similar to `new Error().stack`
```
The first line of the trace will be prefixed with
`${myObject.name}: ${myObject.message}`.
The optional `constructorOpt` argument accepts a function. If given, all frames
above `constructorOpt`, including `constructorOpt`, will be omitted from the
generated stack trace.
The `constructorOpt` argument is useful for hiding implementation
details of error generation from the user. For instance:
```js
function a() {
b();
}
function b() {
c();
}
function c() {
// Create an error without stack trace to avoid calculating the stack trace twice.
const { stackTraceLimit } = Error;
Error.stackTraceLimit = 0;
const error = new Error();
Error.stackTraceLimit = stackTraceLimit;
// Capture the stack trace above function b
Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
throw error;
}
a();
```
#### Parameters
##### targetObject
`object`
##### constructorOpt?
`Function`
#### Returns
`void`
#### Inherited from
[`BlpError`](/javascript/api/core/classes/blperror/).[`captureStackTrace`](/javascript/api/core/classes/blperror/#capturestacktrace)
***
### prepareStackTrace()
> `static` **prepareStackTrace**(`err`, `stackTraces`): `any`
Defined in: docs/node\_modules/@types/node/globals.d.ts:56
#### Parameters
##### err
`Error`
##### stackTraces
`CallSite`\[]
#### Returns
`any`
#### See
https://v8.dev/docs/stack-trace-api#customizing-stack-traces
#### Inherited from
[`BlpError`](/javascript/api/core/classes/blperror/).[`prepareStackTrace`](/javascript/api/core/classes/blperror/#preparestacktrace)
---
---
url: 'https://xbbg.org/javascript/api/core/classes/blpvalidationerror.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:178`)
## Extends
* [`BlpError`](/javascript/api/core/classes/blperror/)
## Constructors
### Constructor
> **new BlpValidationError**(`message?`): `BlpValidationError`
Defined in: docs/node\_modules/typescript/lib/lib.es5.d.ts:1082
#### Parameters
##### message?
`string`
#### Returns
`BlpValidationError`
#### Inherited from
[`BlpError`](/javascript/api/core/classes/blperror/).[`constructor`](/javascript/api/core/classes/blperror/#constructor)
### Constructor
> **new BlpValidationError**(`message?`, `options?`): `BlpValidationError`
Defined in: docs/node\_modules/typescript/lib/lib.es5.d.ts:1082
#### Parameters
##### message?
`string`
##### options?
`ErrorOptions`
#### Returns
`BlpValidationError`
#### Inherited from
[`BlpError`](/javascript/api/core/classes/blperror/).[`constructor`](/javascript/api/core/classes/blperror/#constructor)
## Properties
### cause?
> `optional` **cause?**: `unknown`
Defined in: docs/node\_modules/typescript/lib/lib.es2022.error.d.ts:26
#### Inherited from
[`BlpError`](/javascript/api/core/classes/blperror/).[`cause`](/javascript/api/core/classes/blperror/#cause)
***
### element?
> `readonly` `optional` **element?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:179`)
***
### message
> **message**: `string`
Defined in: docs/node\_modules/typescript/lib/lib.es5.d.ts:1077
#### Inherited from
[`BlpError`](/javascript/api/core/classes/blperror/).[`message`](/javascript/api/core/classes/blperror/#message)
***
### name
> `readonly` **name**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:169`)
#### Inherited from
[`BlpError`](/javascript/api/core/classes/blperror/).[`name`](/javascript/api/core/classes/blperror/#name)
***
### stack?
> `optional` **stack?**: `string`
Defined in: docs/node\_modules/typescript/lib/lib.es5.d.ts:1078
#### Inherited from
[`BlpError`](/javascript/api/core/classes/blperror/).[`stack`](/javascript/api/core/classes/blperror/#stack)
***
### suggestion?
> `readonly` `optional` **suggestion?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:180`)
***
### stackTraceLimit
> `static` **stackTraceLimit**: `number`
Defined in: docs/node\_modules/@types/node/globals.d.ts:68
The `Error.stackTraceLimit` property specifies the number of stack frames
collected by a stack trace (whether generated by `new Error().stack` or
`Error.captureStackTrace(obj)`).
The default value is `10` but may be set to any valid JavaScript number. Changes
will affect any stack trace captured *after* the value has been changed.
If set to a non-number value, or set to a negative number, stack traces will
not capture any frames.
#### Inherited from
[`BlpError`](/javascript/api/core/classes/blperror/).[`stackTraceLimit`](/javascript/api/core/classes/blperror/#stacktracelimit)
## Methods
### captureStackTrace()
> `static` **captureStackTrace**(`targetObject`, `constructorOpt?`): `void`
Defined in: docs/node\_modules/@types/node/globals.d.ts:52
Creates a `.stack` property on `targetObject`, which when accessed returns
a string representing the location in the code at which
`Error.captureStackTrace()` was called.
```js
const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack; // Similar to `new Error().stack`
```
The first line of the trace will be prefixed with
`${myObject.name}: ${myObject.message}`.
The optional `constructorOpt` argument accepts a function. If given, all frames
above `constructorOpt`, including `constructorOpt`, will be omitted from the
generated stack trace.
The `constructorOpt` argument is useful for hiding implementation
details of error generation from the user. For instance:
```js
function a() {
b();
}
function b() {
c();
}
function c() {
// Create an error without stack trace to avoid calculating the stack trace twice.
const { stackTraceLimit } = Error;
Error.stackTraceLimit = 0;
const error = new Error();
Error.stackTraceLimit = stackTraceLimit;
// Capture the stack trace above function b
Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
throw error;
}
a();
```
#### Parameters
##### targetObject
`object`
##### constructorOpt?
`Function`
#### Returns
`void`
#### Inherited from
[`BlpError`](/javascript/api/core/classes/blperror/).[`captureStackTrace`](/javascript/api/core/classes/blperror/#capturestacktrace)
***
### prepareStackTrace()
> `static` **prepareStackTrace**(`err`, `stackTraces`): `any`
Defined in: docs/node\_modules/@types/node/globals.d.ts:56
#### Parameters
##### err
`Error`
##### stackTraces
`CallSite`\[]
#### Returns
`any`
#### See
https://v8.dev/docs/stack-trace-api#customizing-stack-traces
#### Inherited from
[`BlpError`](/javascript/api/core/classes/blperror/).[`prepareStackTrace`](/javascript/api/core/classes/blperror/#preparestacktrace)
---
---
url: 'https://xbbg.org/javascript/api/core/interfaces/bqloptions.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:198`)
## Properties
### backend?
> `optional` **backend?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:201`)
***
### format?
> `optional` **format?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:200`)
***
### kwargs?
> `optional` **kwargs?**: `Record`<`string`, `string` | `number` | `boolean`>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:199`)
---
---
url: 'https://xbbg.org/javascript/api/core/interfaces/bqroptions.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:240`)
## Properties
### backend?
> `optional` **backend?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:245`)
***
### endDatetime?
> `optional` **endDatetime?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:242`)
***
### eventTypes?
> `optional` **eventTypes?**: `string`\[]
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:243`)
***
### includeBrokerCodes?
> `optional` **includeBrokerCodes?**: `boolean`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:244`)
***
### startDatetime?
> `optional` **startDatetime?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:241`)
---
---
url: 'https://xbbg.org/javascript/api/core/interfaces/bsrchoptions.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:212`)
## Properties
### backend?
> `optional` **backend?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:216`)
***
### format?
> `optional` **format?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:215`)
***
### kwargs?
> `optional` **kwargs?**: `Record`<`string`, `string` | `number` | `boolean`>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:214`)
***
### overrides?
> `optional` **overrides?**: `Record`<`string`, `string` | `number` | `boolean`>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:213`)
---
---
url: 'https://xbbg.org/javascript/api/core/interfaces/btaoptions.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:218`)
## Properties
### backend?
> `optional` **backend?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:226`)
***
### endDate?
> `optional` **endDate?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:222`)
***
### format?
> `optional` **format?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:225`)
***
### interval?
> `optional` **interval?**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:224`)
***
### kwargs?
> `optional` **kwargs?**: `Record`<`string`, `string` | `number` | `boolean`>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:220`)
***
### periodicity?
> `optional` **periodicity?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:223`)
***
### startDate?
> `optional` **startDate?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:221`)
***
### studyParams?
> `optional` **studyParams?**: `Record`<`string`, `string` | `number` | `boolean`>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:219`)
---
---
url: 'https://xbbg.org/javascript/api/core/interfaces/cdxnamespace.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:520`)
## Methods
### acdx\_info()
> **acdx\_info**(`ticker`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:521`)
#### Parameters
##### ticker
`string`
##### options?
[`BdpOptions`](/javascript/api/core/interfaces/bdpoptions/)
#### Returns
`Promise`<`Table`<`any`>>
***
### acdx\_pricing()
> **acdx\_pricing**(`ticker`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:522`)
#### Parameters
##### ticker
`string`
##### options?
[`CdxOptions`](/javascript/api/core/interfaces/cdxoptions/)
#### Returns
`Promise`<`Table`<`any`>>
***
### acdx\_risk()
> **acdx\_risk**(`ticker`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:523`)
#### Parameters
##### ticker
`string`
##### options?
[`CdxOptions`](/javascript/api/core/interfaces/cdxoptions/)
#### Returns
`Promise`<`Table`<`any`>>
---
---
url: 'https://xbbg.org/javascript/api/core/interfaces/cdxoptions.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:163`)
## Extends
* [`BdpOptions`](/javascript/api/core/interfaces/bdpoptions/)
## Properties
### backend?
> `optional` **backend?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:133`)
#### Inherited from
[`BdpOptions`](/javascript/api/core/interfaces/bdpoptions/).[`backend`](/javascript/api/core/interfaces/bdpoptions/#backend)
***
### format?
> `optional` **format?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:132`)
#### Inherited from
[`BdpOptions`](/javascript/api/core/interfaces/bdpoptions/).[`format`](/javascript/api/core/interfaces/bdpoptions/#format)
***
### includeSecurityErrors?
> `optional` **includeSecurityErrors?**: `boolean`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:134`)
#### Inherited from
[`BdpOptions`](/javascript/api/core/interfaces/bdpoptions/).[`includeSecurityErrors`](/javascript/api/core/interfaces/bdpoptions/#includesecurityerrors)
***
### kwargs?
> `optional` **kwargs?**: `Record`<`string`, `string` | `number` | `boolean`>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:131`)
#### Inherited from
[`BdpOptions`](/javascript/api/core/interfaces/bdpoptions/).[`kwargs`](/javascript/api/core/interfaces/bdpoptions/#kwargs)
***
### overrides?
> `optional` **overrides?**: `Record`<`string`, `string` | `number` | `boolean`>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:130`)
#### Inherited from
[`BdpOptions`](/javascript/api/core/interfaces/bdpoptions/).[`overrides`](/javascript/api/core/interfaces/bdpoptions/#overrides)
***
### recovery\_rate?
> `optional` **recovery\_rate?**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:165`)
***
### recoveryRate?
> `optional` **recoveryRate?**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:164`)
---
---
url: 'https://xbbg.org/javascript/api/core/interfaces/cdxtickerinfo.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:544`)
## Properties
### asset
> **asset**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:548`)
***
### index
> **index**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:545`)
***
### isGeneric
> **isGeneric**: `boolean`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:549`)
***
### series
> **series**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:546`)
***
### seriesNum?
> `optional` **seriesNum?**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:550`)
***
### tenor
> **tenor**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:547`)
---
---
url: 'https://xbbg.org/releases/changelog.md'
description: Release notes loaded live from the xbbg repository CHANGELOG.md
---
---
---
url: 'https://xbbg.org/python/reference/configuration.md'
description: 'Configure engine settings, pool sizes, and connection options'
---
## configure()
Call `configure()` before any Bloomberg request to set connection parameters, pool sizes, and auth. Once the engine starts on the first request, calling `configure()` again raises `RuntimeError`.
```python
import xbbg
from xbbg import blp, EngineConfig
# Keyword arguments — most common
xbbg.configure(request_pool_size=4, subscription_pool_size=2)
# EngineConfig object
xbbg.configure(EngineConfig(request_pool_size=4, subscription_pool_size=2))
# EngineConfig + overrides (kwargs take precedence)
cfg = EngineConfig(request_pool_size=4)
xbbg.configure(cfg, subscription_pool_size=2)
```
`configure()` is also available on the `blp` module:
```python
from xbbg import blp
blp.configure(host='192.168.1.100', port=18194)
```
::: warning
`configure()` must be called before the first Bloomberg request. Calling it after the engine has started raises `RuntimeError: Cannot configure after engine has started`.
:::
---
## Engine Architecture
xbbg runs a Rust async engine with pre-warmed worker pools:
```
┌─────────────────────────────────────────────────┐
│ xbbg Engine │
│ │
│ ┌──────────────────────┐ ┌─────────────────┐ │
│ │ Request Worker Pool │ │ Subscription │ │
│ │ (request_pool_size) │ │ Session Pool │ │
│ │ │ │ (sub_pool_size) │ │
│ │ Worker 1 ──session │ │ │ │
│ │ Worker 2 ──session │ │ Session 1 │ │
│ │ ... │ │ ... │ │
│ └──────────────────────┘ └─────────────────┘ │
│ │ round-robin │ isolated │
│ ▼ ▼ │
│ bdp/bdh/bds/bdib subscribe/stream │
│ bql/bsrch/beqs vwap/mktbar/depth │
└─────────────────────────────────────────────────┘
```
* **Request workers** each hold an independent Bloomberg session. Concurrent `bdp`/`bdh`/`bds` calls are dispatched round-robin. `request_pool_size=4` allows 4 parallel Bloomberg requests.
* **Subscription sessions** are isolated per session to prevent cross-contamination between topic streams. Each `subscribe()` call gets its own session from the pool.
* Workers are **pre-warmed** at first use — sessions are started and services opened before your first request, eliminating cold-start latency.
***
## EngineConfig Reference
### Connection & Session
| Parameter | Default | Description |
|-----------|---------|-------------|
| `host` | `'localhost'` | Bloomberg server host for direct Terminal/B-PIPE TCP connections |
| `port` | `8194` | Bloomberg server port for direct Terminal/B-PIPE TCP connections |
| `servers` | `[]` | Ordered `(host, port)` failover list for direct TCP connections; do not combine with `zfp_remote` |
| `zfp_remote` | `None` | Bloomberg ZFP leased-line remote, either `'8194'` or `'8196'`; mutually exclusive with `host`/`port`/`servers`/SOCKS5 and requires TLS credentials |
| `num_start_attempts` | `3` | Retries before giving up on session start |
| `auto_restart_on_disconnection` | `True` | Auto-reconnect on session disconnect |
### Worker Pools
| Parameter | Default | Description |
|-----------|---------|-------------|
| `request_pool_size` | `2` | Number of pre-warmed request workers (parallel Bloomberg sessions for bdp/bdh/bds/etc.) |
| `subscription_pool_size` | `1` | Number of pre-warmed subscription sessions (isolated sessions for subscribe/stream) |
| `warmup_services` | `['//blp/refdata', '//blp/apiflds']` | Services to pre-open on startup |
### Subscription Tuning
| Parameter | Default | Description |
|-----------|---------|-------------|
| `subscription_flush_threshold` | `1` | Ticks buffered before flushing to Python. Increase for throughput; decrease for latency |
| `subscription_stream_capacity` | `256` | Backpressure buffer size per subscription stream |
| `overflow_policy` | `'drop_newest'` | Slow consumer policy: `'drop_newest'` or `'block'` |
### Internal Buffers
| Parameter | Default | Description |
|-----------|---------|-------------|
| `max_event_queue_size` | `10000` | Bloomberg SDK event queue depth |
| `command_queue_size` | `256` | Internal command channel capacity |
### Validation
| Parameter | Default | Description |
|-----------|---------|-------------|
| `validation_mode` | `'disabled'` | Field validation: `'disabled'`, `'strict'` (reject unknown fields), or `'lenient'` (warn) |
| `field_cache_path` | `~/.xbbg/field_cache.json` | Path for persistent field type cache |
### Authentication (SAPI / B-PIPE)
| Parameter | Default | Description |
|-----------|---------|-------------|
| `auth_method` | `None` | Auth mode: `'user'`, `'app'`, `'userapp'`, `'dir'`, `'manual'`, or `'token'` |
| `app_name` | `None` | Application name (required for `app`, `userapp`, `manual`) |
| `user_id` | `None` | Bloomberg user ID (required for `manual`) |
| `ip_address` | `None` | Bloomberg IP address (required for `manual`) |
| `dir_property` | `None` | Active Directory property (required for `dir`) |
| `token` | `None` | Auth token (required for `token`) |
***
## Authentication Examples
::: details B-PIPE app
```python
from xbbg import blp
# Application auth — requires app name registered with Bloomberg
blp.configure(
auth_method='app',
app_name='myapp:8888',
host='bpipe-host',
port=8194,
)
```
:::
::: details manual (SAPI)
```python
from xbbg import blp
# Manual auth — provides explicit Bloomberg user and IP
blp.configure(
auth_method='manual',
app_name='myapp',
user_id='12345',
ip_address='10.0.0.1',
)
```
:::
::: details dir
```python
from xbbg import blp
# Active Directory auth — uses an AD property to identify the user
blp.configure(
auth_method='dir',
dir_property='mail',
)
```
:::
::: details token
```python
from xbbg import blp
# Token auth
blp.configure(
auth_method='token',
token='',
)
```
## :::
## Multi-Server Failover
Pass a list of `(host, port)` tuples to `servers`. When set, `servers` overrides `host`/`port`.
```python
from xbbg import blp
blp.configure(
servers=[
('bbg-primary.example.com', 8194),
('bbg-secondary.example.com', 8194),
]
)
```
Bloomberg will attempt servers in order and fall back on failure.
***
## ZFP over Leased Lines
For Bloomberg Zero-Footprint (ZFP) connectivity over private leased lines, set `zfp_remote` to the remote string Bloomberg assigned for the leased-line path. Accepted values are `'8194'` and `'8196'`. xbbg delegates endpoint discovery to Bloomberg's `ZfpUtil::getOptionsForLeasedLines`, so you must not pass direct endpoint settings in the same configuration.
ZFP mode requires both TLS files: `tls_client_credentials` (client PKCS#12 file) and `tls_trust_material` (trust material file). The password is optional only if your client credentials file is not password-protected.
```python
from xbbg import blp
blp.configure(
zfp_remote='8194',
tls_client_credentials='/secure/client.p12',
tls_client_credentials_password='secret',
tls_trust_material='/secure/trust.p7',
)
```
Do not combine `zfp_remote` with `host`, `port`, `servers`, `socks5_host`, or `socks5_port`. In ZFP mode those endpoint addresses are supplied by Bloomberg; passing direct endpoints now raises `ValueError` instead of silently trying `localhost:8194`.
To verify the session start path, enable SDK tracing before `configure()` and confirm the first transport lines contain Bloomberg infrastructure endpoints, not `localhost` or `127.0.0.1`:
```python
import xbbg
from xbbg import blp
xbbg.set_log_level('trace')
xbbg.enable_sdk_logging('trace')
blp.configure(
zfp_remote='8194',
tls_client_credentials='/secure/client.p12',
tls_client_credentials_password='secret',
tls_trust_material='/secure/trust.p7',
)
print(xbbg.is_connected())
```
***
## TLS
| Parameter | Default | Description |
|-----------|---------|-------------|
| `tls_client_credentials` | `None` | Path to client certificate file (PKCS#12) |
| `tls_client_credentials_password` | `None` | Password for the client certificate |
| `tls_trust_material` | `None` | Path to trust store file (PKCS#12) |
| `tls_handshake_timeout_ms` | `None` | TLS handshake timeout in milliseconds |
| `tls_crl_fetch_timeout_ms` | `None` | CRL fetch timeout in milliseconds |
```python
from xbbg import blp
blp.configure(
host='bbg-tls.example.com',
tls_client_credentials='/certs/client.p12',
tls_client_credentials_password='changeit',
tls_trust_material='/certs/trust.p12',
tls_handshake_timeout_ms=5000,
)
```
***
## SOCKS5 Proxy
Route Bloomberg connections through a SOCKS5 proxy by setting both `socks5_host` and `socks5_port`.
| Parameter | Default | Description |
|-----------|---------|-------------|
| `socks5_host` | `None` | SOCKS5 proxy hostname |
| `socks5_port` | `None` | SOCKS5 proxy port (required when `socks5_host` is set) |
```python
from xbbg import blp
blp.configure(
host='bbg-server.example.com',
socks5_host='proxy.internal',
socks5_port=1080,
)
```
***
## Retry Policy
Retries apply to individual Bloomberg requests that fail transiently. Retry is disabled by default (`retry_max_retries=0`).
| Parameter | Default | Description |
|-----------|---------|-------------|
| `retry_max_retries` | `0` | Maximum retry attempts per request. `0` disables retry |
| `retry_initial_delay_ms` | `1000` | Delay before first retry (milliseconds) |
| `retry_backoff_factor` | `2.0` | Multiplier applied to delay after each retry |
| `retry_max_delay_ms` | `30000` | Maximum delay between retries (milliseconds) |
```python
from xbbg import blp
# Retry up to 3 times with exponential backoff: 1s → 2s → 4s (capped at 30s)
blp.configure(
retry_max_retries=3,
retry_initial_delay_ms=1000,
retry_backoff_factor=2.0,
retry_max_delay_ms=30000,
)
```
::: info
Delay sequence: `initial_delay_ms * backoff_factor^n`, capped at `retry_max_delay_ms`. With the defaults above: 1000 ms, 2000 ms, 4000 ms.
:::
---
## SDK Logging
Bloomberg SDK log output is suppressed by default. Two ways to enable it:
**At configure time** — set `sdk_log_level` in `EngineConfig`:
```python
from xbbg import blp
blp.configure(sdk_log_level='INFO')
```
**At runtime** — call `enable_sdk_logging()` after configuration:
```python
import xbbg
xbbg.enable_sdk_logging('DEBUG')
```
Accepted levels are Bloomberg SDK level strings: `'OFF'`, `'FATAL'`, `'ERROR'`, `'WARN'`, `'INFO'`, `'DEBUG'`, `'TRACE'`.
---
---
url: 'https://xbbg.org/javascript/api/core/functions/configure.md'
---
## Call Signature
> **configure**(`config?`): [`EngineConfig`](/javascript/api/core/interfaces/engineconfig/) | `undefined`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:728`)
### Parameters
#### config?
[`EngineConfig`](/javascript/api/core/interfaces/engineconfig/)
### Returns
[`EngineConfig`](/javascript/api/core/interfaces/engineconfig/) | `undefined`
## Call Signature
> **configure**(`host?`, `port?`): [`EngineConfig`](/javascript/api/core/interfaces/engineconfig/) | `undefined`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:729`)
### Parameters
#### host?
`string`
#### port?
`number`
### Returns
[`EngineConfig`](/javascript/api/core/interfaces/engineconfig/) | `undefined`
---
---
url: 'https://xbbg.org/javascript/api/core/functions/connect.md'
---
> **connect**(`config?`): `Promise`<[`Engine`](/javascript/api/core/classes/engine/)>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:727`)
## Parameters
### config?
[`EngineConfig`](/javascript/api/core/interfaces/engineconfig/)
## Returns
`Promise`<[`Engine`](/javascript/api/core/classes/engine/)>
---
---
url: 'https://xbbg.org/javascript/api/core/interfaces/corporatebondsoptions.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:260`)
## Properties
### activeOnly?
> `optional` **activeOnly?**: `boolean`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:263`)
***
### backend?
> `optional` **backend?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:264`)
***
### ccy?
> `optional` **ccy?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:261`)
***
### fields?
> `optional` **fields?**: `string`\[]
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:262`)
---
---
url: 'https://xbbg.org/python/guides/backends.md'
description: 'Choose between pandas, Polars, PyArrow, and more'
---
The backend abstraction is provided by [narwhals](https://github.com/narwhals-dev/narwhals), which handles the translation layer between Arrow and the supported libraries.
## Supported Backends
### Eager Backends
Eager backends return a fully materialized DataFrame immediately.
| Backend | Output type | Best for |
|---------|-------------|----------|
| `pandas` | `pd.DataFrame` | Traditional workflows, ecosystem compatibility |
| `polars` | `pl.DataFrame` | High performance, large datasets |
| `pyarrow` | `pa.Table` | Zero-copy interop, memory efficiency |
| `narwhals` | Narwhals DataFrame | Library-agnostic code |
| `modin` | Modin DataFrame | Pandas API with parallel execution |
| `cudf` | cuDF DataFrame | GPU-accelerated processing (requires NVIDIA) |
### Lazy Backends
Lazy backends defer execution. The query graph is built when you call xbbg functions and evaluated only when you explicitly trigger execution (e.g. `.collect()` for Polars, `.execute()` for DuckDB).
| Backend | Output type | Best for |
|---------|-------------|----------|
| `polars_lazy` | `pl.LazyFrame` | Deferred execution, query optimization |
| `narwhals_lazy` | Narwhals LazyFrame | Library-agnostic lazy evaluation |
| `duckdb` | DuckDB relation | SQL analytics, OLAP queries |
| `dask` | Dask DataFrame | Out-of-core and distributed computing |
| `ibis` | Ibis Table | Unified interface to many backends |
| `pyspark` | Spark DataFrame | Big data processing (requires Java) |
| `sqlframe` | SQLFrame DataFrame | SQL-first DataFrame operations |
::: warning
Lazy backends support `LONG`, `SEMI_LONG`, `LONG_TYPED`, and `LONG_WITH_METADATA` output formats.
:::
## Selecting a Backend
### Global default
Set the backend once for your session. All subsequent calls use it unless overridden.
```python
import xbbg
from xbbg import Backend
xbbg.set_backend(Backend.POLARS)
# All calls now return pl.DataFrame
from xbbg import blp
df = blp.bdp('AAPL US Equity', 'PX_LAST')
```
You can also pass a string:
```python
xbbg.set_backend('polars')
```
### Per-call override
Pass `backend` as a keyword argument to any data function. This overrides the global default for that call only.
```python
from xbbg import blp
# Overrides the global default for this call
df = blp.bdp('AAPL US Equity', 'PX_LAST', backend='pandas')
```
## Checking Availability
Not all backends are installed in every environment. Use these utilities to inspect what is available before writing code that assumes a specific backend.
```python
from xbbg import get_available_backends, is_backend_available, print_backend_status
# Returns a list of installed backend names
print(get_available_backends())
# ['pandas', 'polars', 'pyarrow', ...]
# Check a specific backend
if is_backend_available('polars'):
print("Polars is installed")
# Print a detailed status table for all backends
print_backend_status()
```
## Backend Examples
::: details pandas
```python
from xbbg import blp, Backend
df = blp.bdp('AAPL US Equity', 'PX_LAST', backend=Backend.PANDAS)
# Returns pd.DataFrame
print(type(df)) #
```
:::
::: details polars
```python
from xbbg import blp, Backend
df = blp.bdp('AAPL US Equity', 'PX_LAST', backend=Backend.POLARS)
# Returns pl.DataFrame
print(type(df)) #
```
:::
::: details pyarrow
```python
from xbbg import blp, Backend
table = blp.bdh(
'SPX Index',
'PX_LAST',
start_date='2024-01-01',
end_date='2024-12-31',
backend=Backend.PYARROW,
)
# Returns pa.Table — no copy from the internal representation
print(type(table)) #
```
:::
::: details duckdb
```python
from xbbg import blp, Backend
relation = blp.bdh(
'SPX Index',
'PX_LAST',
start_date='2024-01-01',
end_date='2024-12-31',
backend=Backend.DUCKDB,
)
# Returns a DuckDB relation — not yet executed
result = relation.fetchdf() # trigger execution, returns pd.DataFrame
```
:::
## Performance Considerations
**PyArrow** is the zero-copy option. Because xbbg's internal representation is Arrow, returning a `pa.Table` requires no serialization or memory copy. Use this when passing data to other Arrow-compatible systems (DuckDB, Polars, Spark via Arrow flight, etc.) or when memory pressure matters.
**Polars** is the best choice for pure computation on large datasets. Its columnar engine and lazy execution model handle datasets that would be slow or impractical in pandas. The `polars_lazy` backend lets you chain additional query steps before triggering evaluation.
**pandas** remains the widest-compatibility option. Use it when integrating with libraries that only accept `pd.DataFrame`, or when working with existing pandas-based pipelines. It is not required as a dependency — if your code uses the `polars` or `pyarrow` backends exclusively, pandas does not need to be installed.
**Lazy backends** (DuckDB, Polars lazy, Dask, etc.) are useful when you want to compose queries across multiple xbbg calls before materializing any data, or when the result set is too large to hold in memory.
## Related
* [Output Formats](/python/guides/output-formats/) — control the shape of returned data (LONG, LONG\_TYPED, etc.)
* [API Reference](/python/api/blp/) — full function documentation with all parameters
---
---
url: 'https://xbbg.org/python/guides/dates.md'
description: How xbbg accepts native date / datetime objects across every API surface
---
xbbg accepts native Python date and datetime types on every API surface that
takes a date or datetime. You no longer need to pre-format values to strings
before calling `bdh`, `bdib`, `bdtick`, or any of the `xbbg.ext` helpers — pass
a `datetime.date`, `datetime.datetime`, or a `pandas.Timestamp` directly.
## Accepted types
For any parameter named `start_date`, `end_date`, `dt`, `start_datetime`,
`end_datetime`, `settle_dt`, `expiry_dt`, or `asof`:
| Type | Example | Notes |
|------|---------|-------|
| `str` (ISO 8601) | `"2023-01-17"`, `"2023-01-17T10:30:00"`, `"2023-01-17T10:30:00-05:00"` | Year-leading. Tz suffix preserved. |
| `str` (Bloomberg-native) | `"20230117"` | Compact form, no separators. |
| `str` ("today") | `"today"` | Case-insensitive. Resolves to today's date. |
| `datetime.date` | `date(2023, 1, 17)` | Date portion only. |
| `datetime.datetime` (naive) | `datetime(2023, 1, 17, 10, 30)` | For datetime params, naive values are interpreted via `request_tz`. |
| `datetime.datetime` (aware) | `datetime(2023, 1, 17, tzinfo=ZoneInfo("America/New_York"))` | Timezone preserved end-to-end. |
| `pandas.Timestamp` | `pd.Timestamp("2023-01-17")` | Detected via duck-typing — pandas is **not** a hard dependency. |
## Rejected formats
xbbg rejects ambiguous month/day strings instead of guessing:
```python
blp.bdh("AAPL US Equity", "PX_LAST", start_date="01/17/2023")
# ValueError: Ambiguous date format '01/17/2023': month/day order cannot be inferred.
# Use ISO 8601 (YYYY-MM-DD), Bloomberg-native (YYYYMMDD), or pass a
# datetime.date / datetime.datetime object.
```
## Examples
### Historical data
```python
from datetime import date
import pandas as pd
from xbbg import blp
# String, date, datetime, and pd.Timestamp all work interchangeably.
df = blp.bdh("AAPL US Equity", "PX_LAST", start_date="2023-01-01", end_date="today")
df = blp.bdh("AAPL US Equity", "PX_LAST", start_date=date(2023, 1, 1))
df = blp.bdh("AAPL US Equity", "PX_LAST", start_date=pd.Timestamp("2023-01-01"))
```
### Intraday bars and ticks
```python
from datetime import datetime
from zoneinfo import ZoneInfo
# Naive datetimes are interpreted using request_tz (default UTC).
df = blp.bdtick(
"AAPL US Equity",
start_datetime=datetime(2024, 12, 1, 9, 30),
end_datetime=datetime(2024, 12, 1, 16, 0),
request_tz="exchange",
)
# Tz-aware datetimes preserve their own zone — request_tz is ignored.
df = blp.bdtick(
"AAPL US Equity",
start_datetime=datetime(2024, 12, 1, 9, 30, tzinfo=ZoneInfo("America/New_York")),
end_datetime=datetime(2024, 12, 1, 16, 0, tzinfo=ZoneInfo("America/New_York")),
)
```
### Override-path date values
Bloomberg field overrides (passed as `**kwargs`) also accept native types.
Date-typed values are normalized to `YYYYMMDD` automatically:
```python
from datetime import date
# USER_LOCAL_TRADE_DATE is a Bloomberg date-typed override.
df = blp.bdp(
"AAPL US Equity",
"PX_LAST",
USER_LOCAL_TRADE_DATE=date(2023, 1, 17), # -> "20230117"
)
```
### Bond and option settlement / expiry
```python
from datetime import date
from xbbg.ext.bonds import bond_risk
from xbbg.ext.fixed_income import yas
from xbbg.ext.options import option_chain
bond_risk("T 4.5 05/15/38 Govt", settle_dt=date(2024, 6, 15))
yas("US912810TM69 Govt", "YAS_BOND_YLD", settle_dt=date(2024, 6, 15))
option_chain("AAPL US Equity", expiry_dt=date(2025, 1, 17))
```
## Timezone semantics for intraday requests
| Input shape | Interpretation |
|-------------|----------------|
| `datetime` naive + `request_tz=None` (default) | Treated as UTC. |
| `datetime` naive + `request_tz="exchange"` | Treated as the security's exchange timezone. |
| `datetime` naive + `request_tz="America/New_York"` (any IANA zone) | Treated in that zone. |
| `datetime` aware | Tz preserved; `request_tz` is ignored. |
| `pd.Timestamp` (with `tz`) | Same as aware datetime. |
| `pd.Timestamp` (without `tz`) | Same as naive datetime. |
::: info
The same acceptance set applies to the JS / Node binding (`@xbbg/core`).
JavaScript callers can pass `Date`, ISO 8601 strings, epoch milliseconds, or
duck-typed Luxon `DateTime` (anything with `toJSDate(): Date`). See the
[JS guide](/javascript/) for examples.
:::
---
---
url: 'https://xbbg.org/javascript/api/core/interfaces/dividendoptions.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:274`)
## Properties
### backend?
> `optional` **backend?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:276`)
***
### dvdType?
> `optional` **dvdType?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:275`)
---
---
url: 'https://xbbg.org/javascript/api/core/classes/engine.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:315`)
## Constructors
### Constructor
> **new Engine**(`host?`, `port?`): `Engine`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:316`)
#### Parameters
##### host?
`string`
##### port?
`number`
#### Returns
`Engine`
## Methods
### activeCdx()
> **activeCdx**(`genTicker`, `dt`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:435`)
#### Parameters
##### genTicker
`string`
##### dt
`string`
##### options?
[`ActiveCdxOptions`](/javascript/api/core/interfaces/activecdxoptions/)
#### Returns
`Promise`<`Table`<`any`>>
***
### activeFutures()
> **activeFutures**(`genTicker`, `dt`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:425`)
#### Parameters
##### genTicker
`string`
##### dt
`string`
##### options?
[`FuturesResolveOptions`](/javascript/api/core/interfaces/futuresresolveoptions/)
#### Returns
`Promise`<`Table`<`any`>>
***
### bcurves()
> **bcurves**(`ticker`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:390`)
#### Parameters
##### ticker
`string`
##### options?
[`RequestOptions`](/javascript/api/core/interfaces/requestoptions/)
#### Returns
`Promise`<`Table`<`any`>>
***
### bdh()
> **bdh**(`tickers`, `fields`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:330`)
#### Parameters
##### tickers
`string`\[]
##### fields
`string`\[]
##### options?
[`BdhOptions`](/javascript/api/core/interfaces/bdhoptions/)
#### Returns
`Promise`<`Table`<`any`>>
***
### bdib()
> **bdib**(`ticker`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:335`)
#### Parameters
##### ticker
`string`
##### options?
[`BdibOptions`](/javascript/api/core/interfaces/bdiboptions/)
#### Returns
`Promise`<`Table`<`any`>>
***
### bdp()
> **bdp**(`tickers`, `fields`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:320`)
#### Parameters
##### tickers
`string`\[]
##### fields
`string`\[]
##### options?
[`BdpOptions`](/javascript/api/core/interfaces/bdpoptions/)
#### Returns
`Promise`<`Table`<`any`>>
***
### bds()
> **bds**(`tickers`, `fields`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:325`)
#### Parameters
##### tickers
`string`\[]
##### fields
`string`\[]
##### options?
[`BdpOptions`](/javascript/api/core/interfaces/bdpoptions/)
#### Returns
`Promise`<`Table`<`any`>>
***
### bdtick()
> **bdtick**(`ticker`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:336`)
#### Parameters
##### ticker
`string`
##### options?
[`BdtickOptions`](/javascript/api/core/interfaces/bdtickoptions/)
#### Returns
`Promise`<`Table`<`any`>>
***
### beqs()
> **beqs**(`screen`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:376`)
#### Parameters
##### screen
`string`
##### options?
[`BeqsOptions`](/javascript/api/core/interfaces/beqsoptions/)
#### Returns
`Promise`<`Table`<`any`>>
***
### bflds()
> **bflds**(`options`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:383`)
#### Parameters
##### options
[`BfldsOptions`](/javascript/api/core/interfaces/bfldsoptions/)
#### Returns
`Promise`<`Table`<`any`>>
***
### bgovts()
> **bgovts**(`ticker`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:391`)
#### Parameters
##### ticker
`string`
##### options?
[`RequestOptions`](/javascript/api/core/interfaces/requestoptions/)
#### Returns
`Promise`<`Table`<`any`>>
***
### blkp()
> **blkp**(`query`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:384`)
#### Parameters
##### query
`string`
##### options?
[`BlkpOptions`](/javascript/api/core/interfaces/blkpoptions/)
#### Returns
`Promise`<`Table`<`any`>>
***
### bops()
> **bops**(`service`): `Promise`<`string`\[]>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:405`)
#### Parameters
##### service
`string`
#### Returns
`Promise`<`string`\[]>
***
### bport()
> **bport**(`portfolio`, `fields`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:385`)
#### Parameters
##### portfolio
`string`
Bloomberg PortfolioDataRequest security/portfolio ID string, not the PORT display name
(for example, `UXXXXXXX-X Client` from PRTU/PORT).
##### fields
`string` | `string`\[]
##### options?
[`RequestOptions`](/javascript/api/core/interfaces/requestoptions/)
#### Returns
`Promise`<`Table`<`any`>>
***
### bql()
> **bql**(`query`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:375`)
#### Parameters
##### query
`string`
##### options?
[`BqlOptions`](/javascript/api/core/interfaces/bqloptions/)
#### Returns
`Promise`<`Table`<`any`>>
***
### bqr()
> **bqr**(`ticker`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:409`)
#### Parameters
##### ticker
`string`
##### options?
[`BqrOptions`](/javascript/api/core/interfaces/bqroptions/)
#### Returns
`Promise`<`Table`<`any`>>
***
### bschema()
> **bschema**(`service`, `operation?`): `Promise`<`unknown`>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:406`)
#### Parameters
##### service
`string`
##### operation?
`string`
#### Returns
`Promise`<`unknown`>
***
### bsrch()
> **bsrch**(`searchSpec`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:377`)
#### Parameters
##### searchSpec
`string`
##### options?
[`BsrchOptions`](/javascript/api/core/interfaces/bsrchoptions/)
#### Returns
`Promise`<`Table`<`any`>>
***
### bta()
> **bta**(`ticker`, `study`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:378`)
#### Parameters
##### ticker
`string`
##### study
`string` | `Record`<`string`, `unknown`>
##### options?
[`BtaOptions`](/javascript/api/core/interfaces/btaoptions/)
#### Returns
`Promise`<`Table`<`any`>>
***
### cdxTicker()
> **cdxTicker**(`genTicker`, `dt`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:430`)
#### Parameters
##### genTicker
`string`
##### dt
`string`
##### options?
[`RecipeBackendOptions`](/javascript/api/core/interfaces/recipebackendoptions/)
#### Returns
`Promise`<`Table`<`any`>>
***
### chains()
> **chains**(`ticker`, `options?`): `Promise`<[`Subscription`](/javascript/api/core/classes/subscription/)>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:404`)
#### Parameters
##### ticker
`string`
##### options?
[`StreamOptions`](/javascript/api/core/interfaces/streamoptions/)
#### Returns
`Promise`<[`Subscription`](/javascript/api/core/classes/subscription/)>
***
### clearFieldCache()
> **clearFieldCache**(): `void`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:343`)
#### Returns
`void`
***
### clearSchemaCache()
> **clearSchemaCache**(): `void`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:352`)
#### Returns
`void`
***
### corporateBonds()
> **corporateBonds**(`ticker`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:416`)
#### Parameters
##### ticker
`string`
##### options?
[`CorporateBondsOptions`](/javascript/api/core/interfaces/corporatebondsoptions/)
#### Returns
`Promise`<`Table`<`any`>>
***
### currencyConversion()
> **currencyConversion**(`ticker`, `targetCcy`, `startDate`, `endDate`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:453`)
#### Parameters
##### ticker
`string`
##### targetCcy
`string`
##### startDate
`string`
##### endDate
`string`
##### options?
[`RecipeBackendOptions`](/javascript/api/core/interfaces/recipebackendoptions/)
#### Returns
`Promise`<`Table`<`any`>>
***
### depth()
> **depth**(`ticker`, `options?`): `Promise`<[`Subscription`](/javascript/api/core/classes/subscription/)>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:403`)
#### Parameters
##### ticker
`string`
##### options?
[`StreamOptions`](/javascript/api/core/interfaces/streamoptions/)
#### Returns
`Promise`<[`Subscription`](/javascript/api/core/classes/subscription/)>
***
### dividend()
> **dividend**(`tickers`, `startDate`, `endDate`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:440`)
#### Parameters
##### tickers
`string` | `string`\[]
##### startDate
`string`
##### endDate
`string`
##### options?
[`DividendOptions`](/javascript/api/core/interfaces/dividendoptions/)
#### Returns
`Promise`<`Table`<`any`>>
***
### etfHoldings()
> **etfHoldings**(`etfTicker`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:452`)
#### Parameters
##### etfTicker
`string`
##### options?
[`EtfHoldingsOptions`](/javascript/api/core/interfaces/etfholdingsoptions/)
#### Returns
`Promise`<`Table`<`any`>>
***
### fieldInfo()
> **fieldInfo**(`fields`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:407`)
#### Parameters
##### fields
`string` | `string`\[]
##### options?
[`BfldsOptions`](/javascript/api/core/interfaces/bfldsoptions/)
#### Returns
`Promise`<`Table`<`any`>>
***
### fieldSearch()
> **fieldSearch**(`searchSpec`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:408`)
#### Parameters
##### searchSpec
`string`
##### options?
[`BfldsOptions`](/javascript/api/core/interfaces/bfldsoptions/)
#### Returns
`Promise`<`Table`<`any`>>
***
### futTicker()
> **futTicker**(`genTicker`, `dt`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:420`)
#### Parameters
##### genTicker
`string`
##### dt
`string`
##### options?
[`FuturesResolveOptions`](/javascript/api/core/interfaces/futuresresolveoptions/)
#### Returns
`Promise`<`Table`<`any`>>
***
### getCachedSchema()
> **getCachedSchema**(`service`): `unknown`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:350`)
#### Parameters
##### service
`string`
#### Returns
`unknown`
***
### getEnumValues()
> **getEnumValues**(`service`, `operation`, `element`): `Promise`<`string`\[] | `null`>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:354`)
#### Parameters
##### service
`string`
##### operation
`string`
##### element
`string`
#### Returns
`Promise`<`string`\[] | `null`>
***
### getFieldInfo()
> **getFieldInfo**(`field`): [`FieldInfo`](/javascript/api/core/interfaces/fieldinfo/) | `null`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:342`)
#### Parameters
##### field
`string`
#### Returns
[`FieldInfo`](/javascript/api/core/interfaces/fieldinfo/) | `null`
***
### getOperation()
> **getOperation**(`service`, `operation`): `Promise`<`unknown`>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:348`)
#### Parameters
##### service
`string`
##### operation
`string`
#### Returns
`Promise`<`unknown`>
***
### getSchema()
> **getSchema**(`service`): `Promise`<`unknown`>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:347`)
#### Parameters
##### service
`string`
#### Returns
`Promise`<`unknown`>
***
### invalidateSchema()
> **invalidateSchema**(`service`): `void`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:351`)
#### Parameters
##### service
`string`
#### Returns
`void`
***
### isAvailable()
> **isAvailable**(): `boolean`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:374`)
#### Returns
`boolean`
***
### isFieldValidationEnabled()
> **isFieldValidationEnabled**(): `boolean`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:346`)
#### Returns
`boolean`
***
### listCachedSchemas()
> **listCachedSchemas**(): `string`\[]
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:353`)
#### Returns
`string`\[]
***
### listOperations()
> **listOperations**(`service`): `Promise`<`string`\[]>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:349`)
#### Parameters
##### service
`string`
#### Returns
`Promise`<`string`\[]>
***
### listValidElements()
> **listValidElements**(`service`, `operation`): `Promise`<`string`\[] | `null`>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:359`)
#### Parameters
##### service
`string`
##### operation
`string`
#### Returns
`Promise`<`string`\[] | `null`>
***
### mktbar()
> **mktbar**(`ticker`, `options?`): `Promise`<[`Subscription`](/javascript/api/core/classes/subscription/)>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:402`)
#### Parameters
##### ticker
`string`
##### options?
[`StreamOptions`](/javascript/api/core/interfaces/streamoptions/)
#### Returns
`Promise`<[`Subscription`](/javascript/api/core/classes/subscription/)>
***
### preferreds()
> **preferreds**(`equityTicker`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:415`)
#### Parameters
##### equityTicker
`string`
##### options?
[`PreferredsOptions`](/javascript/api/core/interfaces/preferredsoptions/)
#### Returns
`Promise`<`Table`<`any`>>
***
### request()
> **request**(`params`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:318`)
#### Parameters
##### params
[`RequestInput`](/javascript/api/core/interfaces/requestinput/)
#### Returns
`Promise`<`Table`<`any`>>
***
### requestRaw()
> **requestRaw**(`params`): `Promise`<`Buffer`<`ArrayBufferLike`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:319`)
#### Parameters
##### params
[`RequestInput`](/javascript/api/core/interfaces/requestinput/)
#### Returns
`Promise`<`Buffer`<`ArrayBufferLike`>>
***
### resolveFieldTypes()
> **resolveFieldTypes**(`fields`, `overrides?`, `defaultType?`): `Promise`<`Record`<`string`, `string`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:337`)
#### Parameters
##### fields
`string`\[]
##### overrides?
`Record`<`string`, `string` | `number` | `boolean`>
##### defaultType?
`string`
#### Returns
`Promise`<`Record`<`string`, `string`>>
***
### saveFieldCache()
> **saveFieldCache**(): `void`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:344`)
#### Returns
`void`
***
### signalShutdown()
> **signalShutdown**(): `void`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:373`)
#### Returns
`void`
***
### stream()
> **stream**(`tickers`, `fields`, `options?`): `Promise`<[`Subscription`](/javascript/api/core/classes/subscription/)>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:392`)
#### Parameters
##### tickers
`string`\[]
##### fields
`string`\[]
##### options?
[`StreamOptions`](/javascript/api/core/interfaces/streamoptions/)
#### Returns
`Promise`<[`Subscription`](/javascript/api/core/classes/subscription/)>
***
### subscribe()
> **subscribe**(`tickers`, `fields`): `Promise`<[`Subscription`](/javascript/api/core/classes/subscription/)>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:363`)
#### Parameters
##### tickers
`string`\[]
##### fields
`string`\[]
#### Returns
`Promise`<[`Subscription`](/javascript/api/core/classes/subscription/)>
***
### subscribeWithOptions()
> **subscribeWithOptions**(`service`, `tickers`, `fields`, `options?`, `flushThreshold?`, `overflowPolicy?`, `streamCapacity?`): `Promise`<[`Subscription`](/javascript/api/core/classes/subscription/)>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:364`)
#### Parameters
##### service
`string`
##### tickers
`string`\[]
##### fields
`string`\[]
##### options?
`string`\[]
##### flushThreshold?
`number`
##### overflowPolicy?
`string`
##### streamCapacity?
`number`
#### Returns
`Promise`<[`Subscription`](/javascript/api/core/classes/subscription/)>
***
### turnover()
> **turnover**(`tickers`, `startDate`, `endDate`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:446`)
#### Parameters
##### tickers
`string` | `string`\[]
##### startDate
`string`
##### endDate
`string`
##### options?
[`TurnoverOptions`](/javascript/api/core/interfaces/turnoveroptions/)
#### Returns
`Promise`<`Table`<`any`>>
***
### validateFields()
> **validateFields**(`fields`): `Promise`<`string`\[]>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:345`)
#### Parameters
##### fields
`string`\[]
#### Returns
`Promise`<`string`\[]>
***
### vwap()
> **vwap**(`tickers`, `fields`, `options?`): `Promise`<[`Subscription`](/javascript/api/core/classes/subscription/)>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:397`)
#### Parameters
##### tickers
`string`\[]
##### fields
`string`\[]
##### options?
[`StreamOptions`](/javascript/api/core/interfaces/streamoptions/)
#### Returns
`Promise`<[`Subscription`](/javascript/api/core/classes/subscription/)>
***
### yas()
> **yas**(`tickers`, `fields`, `options?`): `Promise`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:410`)
#### Parameters
##### tickers
`string` | `string`\[]
##### fields
`string` | `string`\[]
##### options?
[`YasOptions`](/javascript/api/core/interfaces/yasoptions/)
#### Returns
`Promise`<`Table`<`any`>>
***
### withConfig()
> `static` **withConfig**(`config?`): `Engine`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:317`)
#### Parameters
##### config?
[`EngineConfig`](/javascript/api/core/interfaces/engineconfig/)
#### Returns
`Engine`
---
---
url: 'https://xbbg.org/javascript/api/core/interfaces/engineconfig.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:43`)
## Properties
### auth?
> `optional` **auth?**: [`AuthConfig`](/javascript/api/core/type-aliases/authconfig/)
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:58`)
***
### autoRestartOnDisconnection?
> `optional` **autoRestartOnDisconnection?**: `boolean`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:61`)
***
### commandQueueSize?
> `optional` **commandQueueSize?**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:53`)
***
### fieldCachePath?
> `optional` **fieldCachePath?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:57`)
***
### host?
> `optional` **host?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:44`)
***
### keepAliveEnabled?
> `optional` **keepAliveEnabled?**: `boolean`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:71`)
Enable BLPAPI keep-alive pings. SDK default: true.
***
### keepAliveInactivityMs?
> `optional` **keepAliveInactivityMs?**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:73`)
Milliseconds of inactivity before keep-alive ping is sent. SDK default: 20000.
***
### keepAliveResponseTimeoutMs?
> `optional` **keepAliveResponseTimeoutMs?**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:75`)
Milliseconds to wait for a keep-alive response. SDK default: 10000.
***
### maxEventQueueSize?
> `optional` **maxEventQueueSize?**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:52`)
***
### numStartAttempts?
> `optional` **numStartAttempts?**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:60`)
***
### overflowPolicy?
> `optional` **overflowPolicy?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:55`)
***
### port?
> `optional` **port?**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:45`)
***
### requestPoolSize?
> `optional` **requestPoolSize?**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:48`)
***
### requestTimeoutMs?
> `optional` **requestTimeoutMs?**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:64`)
Hard per-request timeout in ms; 0 disables. Default 60000.
***
### retryPolicy?
> `optional` **retryPolicy?**: [`RetryPolicy`](/javascript/api/core/interfaces/retrypolicy/)
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:62`)
***
### sdkLogLevel?
> `optional` **sdkLogLevel?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:80`)
***
### servers?
> `optional` **servers?**: [`ServerAddress`](/javascript/api/core/interfaces/serveraddress/)\[]
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:46`)
***
### slowConsumerHiWaterMark?
> `optional` **slowConsumerHiWaterMark?**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:77`)
Slow-consumer hi water mark as fraction of maxEventQueueSize. SDK default: 0.75.
***
### slowConsumerLoWaterMark?
> `optional` **slowConsumerLoWaterMark?**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:79`)
Slow-consumer lo water mark as fraction of maxEventQueueSize. SDK default: 0.5.
***
### socks5?
> `optional` **socks5?**: [`Socks5Config`](/javascript/api/core/interfaces/socks5config/)
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:81`)
***
### streamsDeactivatedWarnMs?
> `optional` **streamsDeactivatedWarnMs?**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:69`)
Warn threshold for a subscription's streams staying deactivated, in ms.
0 disables. Default 30000.
***
### subscriptionFlushThreshold?
> `optional` **subscriptionFlushThreshold?**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:51`)
***
### subscriptionPoolSize?
> `optional` **subscriptionPoolSize?**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:49`)
***
### subscriptionStreamCapacity?
> `optional` **subscriptionStreamCapacity?**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:54`)
***
### tls?
> `optional` **tls?**: [`TlsConfig`](/javascript/api/core/interfaces/tlsconfig/)
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:59`)
***
### validationMode?
> `optional` **validationMode?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:50`)
***
### warmupServices?
> `optional` **warmupServices?**: `string`\[]
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:56`)
***
### zfpRemote?
> `optional` **zfpRemote?**: `"8194"` | `"8196"`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:47`)
---
---
url: 'https://xbbg.org/javascript/api/core/interfaces/etfholdingsoptions.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:283`)
## Properties
### backend?
> `optional` **backend?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:285`)
***
### fields?
> `optional` **fields?**: `string`\[]
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:284`)
---
---
url: 'https://xbbg.org/python/api/exceptions.md'
description: Bloomberg API exception hierarchy and error handling
---
# xbbg.exceptions
Bloomberg API exceptions.
Canonical exception classes are defined by the Rust extension module
(`xbbg._core`) and re-exported here for a stable Python import path.
Python-only exceptions should be additive and inherit from the Rust base.
## BlpRequestError Objects
```python
class BlpRequestError(_core.BlpRequestError)
```
Bloomberg request-level error with extended request context attributes.
## BlpSecurityError Objects
```python
class BlpSecurityError(BlpRequestError)
```
Bloomberg security-level error (request failed for a specific security).
## BlpFieldError Objects
```python
class BlpFieldError(BlpRequestError)
```
Bloomberg field-level error (request failed for a specific field).
## BlpBPipeError Objects
```python
class BlpBPipeError(BlpError)
```
B-PIPE license required for this operation.
Raised when attempting to use features that require Bloomberg B-PIPE
license but only a standard Terminal connection is available.
B-PIPE features include:
\- Level 2 market depth data (depth/adepth)
\- Option and futures chains (chains/achains)
## BlpValidationError Objects
```python
class BlpValidationError(_core.BlpValidationError)
```
Bloomberg validation error with element and suggestion metadata.
#### from\_rust\_error
```python
@classmethod
def from_rust_error(cls, message: str) -> BlpValidationError
```
Construct a BlpValidationError by parsing metadata from a Rust error message.
---
---
url: 'https://xbbg.org/javascript/api/core/interfaces/exchangeinforesult.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:577`)
## Properties
### allday?
> `optional` **allday?**: [`TimeRange`](/javascript/api/core/interfaces/timerange/)
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:585`)
***
### am?
> `optional` **am?**: [`TimeRange`](/javascript/api/core/interfaces/timerange/)
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:588`)
***
### day?
> `optional` **day?**: [`TimeRange`](/javascript/api/core/interfaces/timerange/)
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:584`)
***
### exchCode?
> `optional` **exchCode?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:580`)
***
### mic?
> `optional` **mic?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:579`)
***
### pm?
> `optional` **pm?**: [`TimeRange`](/javascript/api/core/interfaces/timerange/)
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:589`)
***
### post?
> `optional` **post?**: [`TimeRange`](/javascript/api/core/interfaces/timerange/)
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:587`)
***
### pre?
> `optional` **pre?**: [`TimeRange`](/javascript/api/core/interfaces/timerange/)
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:586`)
***
### source
> **source**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:583`)
***
### ticker
> **ticker**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:578`)
***
### timezone
> **timezone**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:581`)
***
### utcOffset?
> `optional` **utcOffset?**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:582`)
---
---
url: 'https://xbbg.org/javascript/api/core/interfaces/exchangeoverrideinput.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:592`)
## Properties
### allday?
> `optional` **allday?**: [`TimeRange`](/javascript/api/core/interfaces/timerange/)
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:597`)
***
### am?
> `optional` **am?**: [`TimeRange`](/javascript/api/core/interfaces/timerange/)
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:600`)
***
### day?
> `optional` **day?**: [`TimeRange`](/javascript/api/core/interfaces/timerange/)
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:596`)
***
### exchCode?
> `optional` **exchCode?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:595`)
***
### mic?
> `optional` **mic?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:594`)
***
### pm?
> `optional` **pm?**: [`TimeRange`](/javascript/api/core/interfaces/timerange/)
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:601`)
***
### post?
> `optional` **post?**: [`TimeRange`](/javascript/api/core/interfaces/timerange/)
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:599`)
***
### pre?
> `optional` **pre?**: [`TimeRange`](/javascript/api/core/interfaces/timerange/)
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:598`)
***
### timezone?
> `optional` **timezone?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:593`)
---
---
url: 'https://xbbg.org/javascript/api/core/variables/ext.md'
---
> `const` **ext**: [`ExtNamespace`](/javascript/api/core/interfaces/extnamespace/)
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:789`)
---
---
url: 'https://xbbg.org/javascript/api/core/interfaces/extnamespace.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:604`)
## Properties
### cdx
> **cdx**: [`CdxNamespace`](/javascript/api/core/interfaces/cdxnamespace/)
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:605`)
## Methods
### buildCorporateBondsQuery()
> **buildCorporateBondsQuery**(`ticker`, `ccy?`, `extraFields?`, `activeOnly?`): `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:694`)
#### Parameters
##### ticker
`string`
##### ccy?
`string`
##### extraFields?
`string`\[]
##### activeOnly?
`boolean`
#### Returns
`string`
***
### buildEarningHeaderRename()
> **buildEarningHeaderRename**(`headerRow`, `dataColumns`): [`StringPair`](/javascript/api/core/interfaces/stringpair/)\[]
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:683`)
#### Parameters
##### headerRow
[`StringPair`](/javascript/api/core/interfaces/stringpair/)\[]
##### dataColumns
`string`\[]
#### Returns
[`StringPair`](/javascript/api/core/interfaces/stringpair/)\[]
***
### buildEtfHoldingsQuery()
> **buildEtfHoldingsQuery**(`etfTicker`, `extraFields?`): `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:700`)
#### Parameters
##### etfTicker
`string`
##### extraFields?
`string`\[]
#### Returns
`string`
***
### buildFuturesTicker()
> **buildFuturesTicker**(`prefix`, `monthCode`, `year`, `asset`): `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:618`)
#### Parameters
##### prefix
`string`
##### monthCode
`string`
##### year
`string`
##### asset
`string`
#### Returns
`string`
***
### buildFxPair()
> **buildFxPair**(`fromCcy`, `toCcy`): [`FxPairInfo`](/javascript/api/core/interfaces/fxpairinfo/)
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:655`)
#### Parameters
##### fromCcy
`string`
##### toCcy
`string`
#### Returns
[`FxPairInfo`](/javascript/api/core/interfaces/fxpairinfo/)
***
### buildPreferredsQuery()
> **buildPreferredsQuery**(`equityTicker`, `extraFields?`): `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:693`)
#### Parameters
##### equityTicker
`string`
##### extraFields?
`string`\[]
#### Returns
`string`
***
### buildYasOverrides()
> **buildYasOverrides**(`settleDt?`, `yieldType?`, `spread?`, `yieldVal?`, `price?`, `benchmark?`): [`StringPair`](/javascript/api/core/interfaces/stringpair/)\[]
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:673`)
#### Parameters
##### settleDt?
`string`
##### yieldType?
`number`
##### spread?
`number`
##### yieldVal?
`number`
##### price?
`number`
##### benchmark?
`string`
#### Returns
[`StringPair`](/javascript/api/core/interfaces/stringpair/)\[]
***
### calculateLevelPercentages()
> **calculateLevelPercentages**(`values`, `levels`): (`number` | `null`)\[]
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:687`)
#### Parameters
##### values
(`number` | `null`)\[]
##### levels
(`number` | `null`)\[]
#### Returns
(`number` | `null`)\[]
***
### cdxGenToSpecific()
> **cdxGenToSpecific**(`genTicker`, `series`): `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:652`)
#### Parameters
##### genTicker
`string`
##### series
`number`
#### Returns
`string`
***
### clearExchangeOverride()
> **clearExchangeOverride**(`ticker?`): `void`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:717`)
#### Parameters
##### ticker?
`string`
#### Returns
`void`
***
### contractIndex()
> **contractIndex**(`genTicker`): `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:637`)
#### Parameters
##### genTicker
`string`
#### Returns
`number`
***
### currenciesNeedingConversion()
> **currenciesNeedingConversion**(`currencies`, `target`): `string`\[]
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:657`)
#### Parameters
##### currencies
`string`\[]
##### target
`string`
#### Returns
`string`\[]
***
### defaultBqrDatetimes()
> **defaultBqrDatetimes**(`startDatetime?`, `endDatetime?`): [`TimeRange`](/javascript/api/core/interfaces/timerange/)
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:704`)
#### Parameters
##### startDatetime?
`string`
##### endDatetime?
`string`
#### Returns
[`TimeRange`](/javascript/api/core/interfaces/timerange/)
***
### defaultTurnoverDates()
> **defaultTurnoverDates**(`startDate?`, `endDate?`): [`TimeRange`](/javascript/api/core/interfaces/timerange/)
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:703`)
#### Parameters
##### startDate?
`string`
##### endDate?
`string`
#### Returns
[`TimeRange`](/javascript/api/core/interfaces/timerange/)
***
### deriveSessions()
> **deriveSessions**(`dayStart`, `dayEnd`, `mic?`, `exchCode?`): [`SessionWindowsInfo`](/javascript/api/core/interfaces/sessionwindowsinfo/)
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:707`)
#### Parameters
##### dayStart
`string`
##### dayEnd
`string`
##### mic?
`string`
##### exchCode?
`string`
#### Returns
[`SessionWindowsInfo`](/javascript/api/core/interfaces/sessionwindowsinfo/)
***
### filterCandidatesByCycle()
> **filterCandidatesByCycle**(`candidates`, `cycle`): [`FuturesCandidate`](/javascript/api/core/interfaces/futurescandidate/)\[]
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:638`)
#### Parameters
##### candidates
[`FuturesCandidate`](/javascript/api/core/interfaces/futurescandidate/)\[]
##### cycle
`string`
#### Returns
[`FuturesCandidate`](/javascript/api/core/interfaces/futurescandidate/)\[]
***
### filterEquityTickers()
> **filterEquityTickers**(`tickers`): `string`\[]
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:625`)
#### Parameters
##### tickers
`string`\[]
#### Returns
`string`\[]
***
### filterValidContracts()
> **filterValidContracts**(`contracts`, `year`, `month`, `day`): `string`\[]
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:642`)
#### Parameters
##### contracts
[`StringPair`](/javascript/api/core/interfaces/stringpair/)\[]
##### year
`number`
##### month
`number`
##### day
`number`
#### Returns
`string`\[]
***
### fmtDate()
> **fmtDate**(`year`, `month`, `day`, `fmt?`): `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:609`)
#### Parameters
##### year
`number`
##### month
`number`
##### day
`number`
##### fmt?
`string`
#### Returns
`string`
***
### generateFuturesCandidates()
> **generateFuturesCandidates**(`genTicker`, `year`, `month`, `day`, `freq?`, `count?`): [`FuturesCandidate`](/javascript/api/core/interfaces/futurescandidate/)\[]
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:628`)
#### Parameters
##### genTicker
`string`
##### year
`number`
##### month
`number`
##### day
`number`
##### freq?
`string`
##### count?
`number`
#### Returns
[`FuturesCandidate`](/javascript/api/core/interfaces/futurescandidate/)\[]
***
### getDvdCols()
> **getDvdCols**(): [`StringPair`](/javascript/api/core/interfaces/stringpair/)\[]
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:669`)
#### Returns
[`StringPair`](/javascript/api/core/interfaces/stringpair/)\[]
***
### getDvdType()
> **getDvdType**(`typ`): `string` | `null`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:667`)
#### Parameters
##### typ
`string`
#### Returns
`string` | `null`
***
### getDvdTypes()
> **getDvdTypes**(): [`StringPair`](/javascript/api/core/interfaces/stringpair/)\[]
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:668`)
#### Returns
[`StringPair`](/javascript/api/core/interfaces/stringpair/)\[]
***
### getEtfCols()
> **getEtfCols**(): [`StringPair`](/javascript/api/core/interfaces/stringpair/)\[]
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:670`)
#### Returns
[`StringPair`](/javascript/api/core/interfaces/stringpair/)\[]
***
### getExchangeOverride()
> **getExchangeOverride**(`ticker`): [`ExchangeInfoResult`](/javascript/api/core/interfaces/exchangeinforesult/) | `null`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:716`)
#### Parameters
##### ticker
`string`
#### Returns
[`ExchangeInfoResult`](/javascript/api/core/interfaces/exchangeinforesult/) | `null`
***
### getFuturesMonths()
> **getFuturesMonths**(): [`StringPair`](/javascript/api/core/interfaces/stringpair/)\[]
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:666`)
#### Returns
[`StringPair`](/javascript/api/core/interfaces/stringpair/)\[]
***
### getMarketRule()
> **getMarketRule**(`mic?`, `exchCode?`): [`MarketRule`](/javascript/api/core/interfaces/marketrule/) | `null`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:713`)
#### Parameters
##### mic?
`string`
##### exchCode?
`string`
#### Returns
[`MarketRule`](/javascript/api/core/interfaces/marketrule/) | `null`
***
### getMonthCode()
> **getMonthCode**(`monthName`): `string` | `null`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:664`)
#### Parameters
##### monthName
`string`
#### Returns
`string` | `null`
***
### getMonthName()
> **getMonthName**(`code`): `string` | `null`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:665`)
#### Parameters
##### code
`string`
#### Returns
`string` | `null`
***
### inferTimezone()
> **inferTimezone**(`countryIso`): `string` | `null`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:714`)
#### Parameters
##### countryIso
`string`
#### Returns
`string` | `null`
***
### isLongFormat()
> **isLongFormat**(`ipcBuffer`): `boolean`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:613`)
#### Parameters
##### ipcBuffer
`Buffer`
#### Returns
`boolean`
***
### isSpecificContract()
> **isSpecificContract**(`ticker`): `boolean`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:617`)
#### Parameters
##### ticker
`string`
#### Returns
`boolean`
***
### listExchangeOverrides()
> **listExchangeOverrides**(): [`ExchangeInfoResult`](/javascript/api/core/interfaces/exchangeinforesult/)\[]
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:718`)
#### Returns
[`ExchangeInfoResult`](/javascript/api/core/interfaces/exchangeinforesult/)\[]
***
### normalizeTickers()
> **normalizeTickers**(`tickers`): `string`\[]
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:624`)
#### Parameters
##### tickers
`string`\[]
#### Returns
`string`\[]
***
### parseCdxTicker()
> **parseCdxTicker**(`ticker`): [`CdxTickerInfo`](/javascript/api/core/interfaces/cdxtickerinfo/)
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:650`)
#### Parameters
##### ticker
`string`
#### Returns
[`CdxTickerInfo`](/javascript/api/core/interfaces/cdxtickerinfo/)
***
### parseDate()
> **parseDate**(`dateStr`): `number`\[]
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:608`)
#### Parameters
##### dateStr
`string`
#### Returns
`number`\[]
***
### parseTicker()
> **parseTicker**(`ticker`): [`TickerParts`](/javascript/api/core/interfaces/tickerparts/)
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:616`)
#### Parameters
##### ticker
`string`
#### Returns
[`TickerParts`](/javascript/api/core/interfaces/tickerparts/)
***
### pivotToWide()
> **pivotToWide**(`ipcBuffer`): `Buffer`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:612`)
#### Parameters
##### ipcBuffer
`Buffer`
#### Returns
`Buffer`
***
### previousCdxSeries()
> **previousCdxSeries**(`ticker`): `string` | `null`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:651`)
#### Parameters
##### ticker
`string`
#### Returns
`string` | `null`
***
### renameDividendColumns()
> **renameDividendColumns**(`columns`): [`StringPair`](/javascript/api/core/interfaces/stringpair/)\[]
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:660`)
#### Parameters
##### columns
`string`\[]
#### Returns
[`StringPair`](/javascript/api/core/interfaces/stringpair/)\[]
***
### renameEtfColumns()
> **renameEtfColumns**(`columns`): [`StringPair`](/javascript/api/core/interfaces/stringpair/)\[]
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:661`)
#### Parameters
##### columns
`string`\[]
#### Returns
[`StringPair`](/javascript/api/core/interfaces/stringpair/)\[]
***
### sameCurrency()
> **sameCurrency**(`ccy1`, `ccy2`): `boolean`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:656`)
#### Parameters
##### ccy1
`string`
##### ccy2
`string`
#### Returns
`boolean`
***
### sessionTimesToUtc()
> **sessionTimesToUtc**(`startTime`, `endTime`, `exchangeTz`, `date`): [`TimeRange`](/javascript/api/core/interfaces/timerange/)
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:719`)
#### Parameters
##### startTime
`string`
##### endTime
`string`
##### exchangeTz
`string`
##### date
`string`
#### Returns
[`TimeRange`](/javascript/api/core/interfaces/timerange/)
***
### setExchangeOverride()
> **setExchangeOverride**(`ticker`, `input`): `void`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:715`)
#### Parameters
##### ticker
`string`
##### input
[`ExchangeOverrideInput`](/javascript/api/core/interfaces/exchangeoverrideinput/)
#### Returns
`void`
***
### validateGenericTicker()
> **validateGenericTicker**(`ticker`): `void`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:636`)
#### Parameters
##### ticker
`string`
#### Returns
`void`
---
---
url: 'https://xbbg.org/javascript/api/core/interfaces/fieldinfo.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:122`)
## Properties
### arrowType
> **arrowType**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:124`)
***
### category
> **category**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:126`)
***
### description
> **description**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:125`)
***
### fieldId
> **fieldId**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:123`)
---
---
url: 'https://xbbg.org/python/guides/fixed-income.md'
description: Bloomberg fixed-income workflows in xbbg
---
::: warning
These examples require appropriate Bloomberg licenses, entitlements, and connectivity for the requested services and instruments.
:::
## Workflow map
## Discover curves and government securities
```python
from xbbg import blp
# List USD government curves
curves = blp.bcurves(currency='USD', curve_type='GOVERNMENT')
# Search for US Treasury securities
govts = blp.bgovts('T')
# Exact match only
specific = blp.bgovts('T 2.5 05/15/24', partial_match=False)
```
`bcurves()` searches yield curves by country, currency, curve type, subtype, curve ID, or Bloomberg Global ID. `bgovts()` searches government securities by ticker or name.
## Request dealer quotes with BQR
```python
from xbbg import blp
quotes = blp.bqr(
'US037833FB15@MSG1 Corp',
date_offset='-2d',
include_broker_codes=True,
include_spread_price=True,
include_yield=True,
)
```
BQR retrieves dealer quote data using BID / ASK events by default and supports date offsets such as `-2d`, `-1w`, and `-3h`. Use `start_date` / `end_date` for explicit windows, or `event_types=['TRADE']` when you only want trade events.
## Use async variants for services
```python
import asyncio
from xbbg import blp
async def main():
curves, quotes = await asyncio.gather(
blp.abcurves(currency='USD', curve_type='GOVERNMENT'),
blp.abqr(
'US037833FB15@MSG1 Corp',
date_offset='-2d',
include_broker_codes=True,
include_spread_price=True,
include_yield=True,
),
)
return curves, quotes
curves, quotes = asyncio.run(main())
```
The async variants use the same parameter shape as the blocking helpers and run through the shared Rust worker pool.
## YAS and bond analytics
The generated Python API exposes Bloomberg request helpers such as `bqr`, `bcurves`, and `bgovts`. Higher-level fixed-income analytics live under `xbbg.ext` where available in the installed package.
```python
from datetime import date
from xbbg.ext.fixed_income import yas
from xbbg.ext.bonds import bond_risk, bond_cashflows
yield_table = yas(
'US912810TM69 Govt',
'YAS_BOND_YLD',
settle_dt=date(2024, 6, 15),
)
risk = bond_risk('T 4.5 05/15/38 Govt', settle_dt=date(2024, 6, 15))
cashflows = bond_cashflows('T 4.5 05/15/38 Govt')
```
Use these helpers when the workflow is about analytics rather than raw field retrieval: yield analysis, duration, convexity, DV01, spreads, cashflow schedules, and key-rate risk.
## Corporate bonds and preferreds
```python
from xbbg.ext import corporate_bonds, preferreds
issuer_bonds = corporate_bonds('AAPL US Equity')
issuer_preferreds = preferreds('BAC US Equity')
```
These helpers are useful for issuer-linked discovery workflows before requesting reference fields, quote history, or risk analytics for individual securities.
## Output and middleware
Fixed-income helpers use the same production controls as the rest of xbbg:
```python
from xbbg import blp
@blp.add_middleware
async def audit_fixed_income(context, call_next):
context.metadata['desk'] = 'fixed-income'
return await call_next(context)
```
Request middleware is the right place to attach desk tags, request IDs, tracing spans, metrics, entitlement checks, or policy decisions across all fixed-income calls.
## Related pages
---
---
url: 'https://xbbg.org/javascript/api/core/variables/format.md'
---
> `const` **Format**: `Readonly`<{ `LONG`: `"long"`; `LONG_TYPED`: `"long_typed"`; `LONG_WITH_METADATA`: `"long_with_metadata"`; `SEMI_LONG`: `"semi_long"`; }>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:191`)
---
---
url: 'https://xbbg.org/javascript/api/core/interfaces/futurescandidate.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:538`)
## Properties
### month
> **month**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:541`)
***
### ticker
> **ticker**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:539`)
***
### year
> **year**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:540`)
---
---
url: 'https://xbbg.org/javascript/api/core/interfaces/futuresresolveoptions.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:266`)
## Properties
### backend?
> `optional` **backend?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:268`)
***
### freq?
> `optional` **freq?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:267`)
---
---
url: 'https://xbbg.org/javascript/api/core/interfaces/fxpairinfo.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:553`)
## Properties
### factor
> **factor**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:555`)
***
### fromCcy
> **fromCcy**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:556`)
***
### fxPair
> **fxPair**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:554`)
***
### toCcy
> **toCcy**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:557`)
---
---
url: 'https://xbbg.org/javascript/api/core/functions/getloglevel.md'
---
> **getLogLevel**(): `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:792`)
## Returns
`string`
---
---
url: 'https://xbbg.org/javascript/installation.md'
description: Install @xbbg/core and understand its native packaging model
---
## Install from a package manager
:::: details npm
```bash
npm install @xbbg/core
```
::::
:::: details bun
```bash
bun add @xbbg/core
```
::::
Package page: [npm / @xbbg/core](https://www.npmjs.com/package/@xbbg/core)
`@xbbg/core` loads a packaged native addon through platform-specific optional dependencies on supported targets.
## Supported prebuilt addon targets
::: info
The platform-specific `@xbbg/core-*` packages are installation artifacts behind `@xbbg/core`. Public docs stay centered on `@xbbg/core` itself.
:::
## Bloomberg connectivity
After install, point the package at the Bloomberg endpoint you use:
```ts
import * as xbbg from '@xbbg/core';
xbbg.configure({
host: 'localhost',
port: 8194,
});
```
For B-PIPE, leased-line, or advanced auth scenarios, `connect()` and `configure()` accept the structured `EngineConfig` object exposed by the package. Direct B-PIPE hosts use `host` / `port` or `servers`; ZFP over leased lines uses `zfpRemote: '8194' | '8196'` plus `tls` credentials and must not be combined with direct hosts or SOCKS5.
## Verify the package surface
```ts
import * as xbbg from '@xbbg/core';
console.log(xbbg.version());
console.log(xbbg.blp);
console.log(xbbg.ext);
```
## Unsupported platforms or source builds
If you need to build the addon yourself, follow the repository instructions in [`js-xbbg/README.md`](https://github.com/underloam/xbbg/blob/main/js-xbbg/README.md). The public docs stay focused on the installable package; contributor and unsupported-platform workflows live in the package README.
## Next steps
---
---
url: 'https://xbbg.org/python/installation.md'
description: Install xbbg and set up the Bloomberg runtime
---
## Requirements
For ZFP over leased lines, you also need Bloomberg-provided TLS client credentials and trust material. See [Configuration: ZFP over Leased Lines](/python/reference/configuration/#zfp-over-leased-lines) for the exact `configure()` call and mutually exclusive connection options.
## Install xbbg
```bash
pip install xbbg
```
Package page: [PyPI / xbbg](https://pypi.org/project/xbbg/)
## Provide the Bloomberg SDK runtime
:::: details Official `blpapi` package (recommended)
```bash
pip install blpapi --index-url https://blpapi.bloomberg.com/repository/releases/python/simple/
```
xbbg detects the SDK files bundled with the official Bloomberg Python bindings when they are available.
::::
:::: details Bloomberg Terminal install
If Bloomberg Terminal is installed, xbbg can detect the DAPI SDK from common locations:
* Windows: `C:\blp\DAPI`
* Linux: `~/blp/DAPI` or `/opt/bloomberg/DAPI`
::::
:::: details Manual SDK path
For local development from this repository, use the bundled helper:
```bash
bash ./scripts/sdktool.sh
```
Or set `BLPAPI_ROOT` manually:
```bash
export BLPAPI_ROOT=/path/to/blpapi_cpp_3.x.x.x
```
Or configure the path at runtime:
```python
import xbbg
xbbg.set_sdk_path('/path/to/blpapi_cpp_3.x.x.x')
```
::::
## Verify installation
```python
import xbbg
print(xbbg.get_sdk_info())
print(xbbg.__version__)
```
::: tip
Run `xbbg.get_sdk_info()` to see every detected SDK source and which one is active.
:::
## Configure your first connection
```python
import xbbg
xbbg.configure(
host='localhost',
port=8194,
auth='OS_LOGON',
)
```
For B-PIPE/SAPI, ZFP, TLS, failover, SOCKS5, SDK logging, and middleware-ready diagnostics, continue to [Configuration](/python/reference/configuration/).
## Optional: install xbbg-mcp for coding agents
If you want Claude Code or OpenCode to call Bloomberg directly, install the local MCP launcher and binary from GitHub Releases:
```bash
curl -fsSL https://raw.githubusercontent.com/underloam/xbbg/main/scripts/install-xbbg-mcp.sh | sh
```
This installer currently targets **macOS arm64** and **Linux amd64**. Windows release `.zip` assets are attached to GitHub Releases for manual installation.
GitHub release assets include only the xbbg wrapper/binary pair. They do **not** bundle Bloomberg SDK files or the Bloomberg runtime; you must provide those locally via `blpapi`, `BLPAPI_ROOT`, or another supported runtime source.
The launcher uses the same Bloomberg runtime detection order as the Python package family:
1. `XBBG_MCP_LIB_DIR`
2. `BLPAPI_LIB_DIR`
3. `BLPAPI_ROOT`
4. vendored SDK under `vendor/blpapi-sdk/`
5. the official Python `blpapi` package
### Claude Code
```bash
claude mcp add --transport stdio xbbg -- ~/.local/bin/xbbg-mcp
```
### OpenCode
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"xbbg": {
"type": "local",
"command": ["/Users/you/.local/bin/xbbg-mcp"],
"enabled": true
}
}
}
```
For the full env surface and local smoke test instructions, see [`apps/xbbg-mcp/README.md`](https://github.com/underloam/xbbg/blob/main/apps/xbbg-mcp/README.md).
## Next steps
---
---
url: 'https://xbbg.org/javascript.md'
description: Public documentation for the @xbbg/core Node.js package
---
## What you get
## Public surface today
* Bloomberg data request helpers for point-in-time, historical, bulk, intraday bar, tick, and subscription workflows
* Structured `EngineConfig` support for host/port, ordered failover, auth, TLS, ZFP, SOCKS5, and recovery tuning
* Public namespaces such as `xbbg.blp` and `xbbg.ext` for core requests and higher-level helpers
* Fixed-income and analytics helpers such as YAS, corporate bonds, preferreds, BQR, curves, and government securities where exposed by the generated package surface
* Arrow-native tables and a generated TypeScript reference for the current package surface
## Quick example
```ts
import * as xbbg from '@xbbg/core';
xbbg.configure({ host: 'localhost', port: 8194 });
const hist = await xbbg.blp.abdh(
['AAPL US Equity'],
['PX_LAST'],
'2024-01-01',
'2024-01-31',
);
```
## Runtime model
## Next steps
---
---
url: 'https://xbbg.org/javascript/api/core/interfaces/marketrule.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:569`)
## Properties
### isContinuous
> **isContinuous**: `boolean`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:574`)
***
### lunchEndMin?
> `optional` **lunchEndMin?**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:573`)
***
### lunchStartMin?
> `optional` **lunchStartMin?**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:572`)
***
### postMinutes
> **postMinutes**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:571`)
***
### preMinutes
> **preMinutes**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:570`)
---
---
url: 'https://xbbg.org/python/guides/migration.md'
description: Upgrading from xbbg < 1.0 to the new Rust-powered backend
---
xbbg 1.0 replaces the pure-Python 0.x implementation with a Rust-powered core. The public function
names you already use (`bdp`, `bdh`, `bdib`, etc.) still exist with the same call shapes, but
**output formats, dependencies, several utility functions, and the connection lifecycle have all
changed**. This guide is a comprehensive walkthrough of every breaking change, with concrete
before/after examples and migration recipes.
::: warning
The `main` branch is xbbg 1.0. If you need exact 0.x behavior, install from the maintained
`release/0.x` branch — there is no shim layer that restores the old defaults. Migration is
required, but most call sites change only by one or two parameters.
:::
## At-a-glance summary
| Area | xbbg 0.x | xbbg 1.0 |
|------|----------|----------|
| Engine | Pure Python wrapping the Bloomberg Python wheel | Rust core, zero-copy Arrow transport into Python |
| Default output format | Wide (ticker as index / MultiIndex columns) | Long (`ticker`, `field`, `value` rows) |
| pandas dependency | Required hard dependency | Optional — install separately |
| Default DataFrame backend | pandas | narwhals (lazy) |
| Core dependencies | pandas | narwhals ≥ 1.30, pyarrow ≥ 22 |
| Connection setup | `blp.connect()` / `blp.disconnect()` | `xbbg.configure()` — engine auto-starts on first use |
| Authentication | `connect(auth_method=…, app_name=…)` | `configure(auth_method=…, app_name=…)` — same fields, six methods |
| Bloomberg SDK at runtime | `pip install blpapi` (vendor wheel bundles `libblpapi3_64`) | Same — `pip install blpapi`, no system C++ SDK install needed (1.0.1+) |
| MultiIndex columns from `bdh` | Yes | Removed — pivot afterwards |
| Async support | `abdp` / `abdh` / etc. wrapping a thread pool | `abdp` / `abdh` / etc. backed by true async Rust I/O |
| Field metadata lookup | `fieldInfo()` / `fieldSearch()` | `bfld()` / `bflds()` (aliases of each other; the legacy names also still work) |
| Portfolio helper | `getPortfolio()` | `bport()` |
| Security lookup | `lookupSecurity(name)` | `blkp(query, yellowkey='YK_FILTER_*')` |
| Equity screening param | `beqs(screen, typ=…)` | `beqs(screen, screen_type=…)` |
| Subscription / streaming | `live()` async generator, `subscribe()` context manager | `stream()` / `subscribe()` / `asubscribe()` returning `Subscription` objects, yielding DataFrames |
| Extension functions (dividends, earnings, options, bonds, CDX, currency) | Top-level on `xbbg.blp` | Moved under `xbbg.ext` |
| `asset_config()` | Returns empty DataFrame (deprecated since 0.12.x) | Removed — use `xbbg.markets.market_info(ticker)` |
| Bloomberg SDK version query | `blp.getBlpapiVersion()` | `xbbg.get_sdk_info()` (returns dict) |
| Middleware / hooks | None | `add_middleware()` / `remove_middleware()` chain around every request |
| Exception hierarchy | Generic `RuntimeError`, often swallowed | `BlpErrorBase` with `BlpSessionError`, `BlpBPipeError`, `BlpRequestError`, `BlpValidationError`, `BlpTimeoutError`, `BlpFieldError`, `BlpSecurityError`, `BlpInternalError` |
| Python minimum | 3.8+ | 3.10+ |
| Source layout | `xbbg/` at repo root | `py-xbbg/src/` |
## Install & runtime requirements
### Runtime
`pip install xbbg blpapi` is sufficient on **Linux, macOS, and Windows**. xbbg 1.0.1 and later
locate `libblpapi3_64.so` from the `blpapi` Python package automatically at first import — there
is no need to install the Bloomberg C++ SDK at runtime, set `LD_LIBRARY_PATH` /
`DYLD_LIBRARY_PATH`, or use `install_name_tool`.
The `blpapi` Python wheel from Bloomberg ships the C library bundled inside the package
(`site-packages/blpapi/libblpapi3_64.so`). xbbg's preload step (`xbbg._sdk._preload_sdk_library`,
fired from `xbbg/__init__.py`) `dlopen`s it before the native engine module loads, so the engine's
`@rpath/libblpapi3_64.so` dependency resolves against the already-loaded image.
::: info
The published **1.0.0** wheel did not yet include the cross-platform preload step. macOS and
Linux users on exactly 1.0.0 need the workaround
`LD_LIBRARY_PATH=$(python -c 'import os, blpapi; print(os.path.dirname(blpapi.__file__))')`
(Linux) or the equivalent `DYLD_LIBRARY_PATH` setting (macOS). Upgrading to 1.0.1+ removes the
need for this entirely.
:::
### Build from source
If you are building xbbg from source rather than installing a wheel, you do still need the full
Bloomberg C++ SDK (headers and import library) at build time. Set `BLPAPI_ROOT` to the extracted
SDK directory before running `pip install -e .` or `pixi run install`. The build script accepts
`BLPAPI_INCLUDE_DIR` + `BLPAPI_LIB_DIR` as an alternative.
### Python version
xbbg 1.0 requires Python 3.10+. Python 3.8 and 3.9 are no longer supported. CPython 3.10 through
3.14 are tested.
## Output format migration
The largest behavioral change is the default output shape.
xbbg 0.x defaulted to **wide** format: `bdp` returned a DataFrame with tickers as the index and
field names as columns; `bdh` with multiple tickers returned a DataFrame with a two-level
MultiIndex on the columns axis `(ticker, field)`.
xbbg 1.0 defaults to **long** format: every function returns one row per (ticker, field)
observation with a `value` column. Long format is tidy data — it composes directly with `groupby`,
`merge`, and filter operations without unpacking MultiIndex levels, and it is the natural shape
for an Arrow-backed engine.
### BDP before and after
::: details 0.x — wide default
```python
from xbbg import blp
df = blp.bdp(
['AAPL US Equity', 'MSFT US Equity'],
['PX_LAST', 'VOLUME'],
)
# pandas DataFrame — ticker as index, fields as columns
# px_last volume
# AAPL US Equity
# MSFT US Equity
price = df.loc['AAPL US Equity', 'px_last']
```
:::
::: details 1.0 — long default
```python
from xbbg import blp
df = blp.bdp(
['AAPL US Equity', 'MSFT US Equity'],
['PX_LAST', 'VOLUME'],
)
# narwhals DataFrame — ticker, field, value columns
# ticker field value
# AAPL US Equity PX_LAST
# AAPL US Equity VOLUME
# MSFT US Equity PX_LAST
# MSFT US Equity VOLUME
```
:::
### BDH before and after
::: details 0.x — MultiIndex columns
```python
from xbbg import blp
df = blp.bdh(
['AAPL US Equity', 'MSFT US Equity'],
'PX_LAST',
'2024-01-01', '2024-01-05',
)
# MultiIndex columns: (ticker, field)
# (AAPL US Equity, PX_LAST) (MSFT US Equity, PX_LAST)
# date
# 2024-01-02
```
:::
::: details 1.0 — long default
```python
from xbbg import blp
df = blp.bdh(
['AAPL US Equity', 'MSFT US Equity'],
'PX_LAST',
'2024-01-01', '2024-01-05',
)
# long format — ticker, date, field, value columns
# ticker date field value
# AAPL US Equity 2024-01-02 PX_LAST
# AAPL US Equity 2024-01-03 PX_LAST
# MSFT US Equity 2024-01-02 PX_LAST
# MSFT US Equity 2024-01-03 PX_LAST
```
:::
### Native datetime / date acceptance (1.x)
Every surface that takes a date or datetime — `bdh` / `bdib` / `bdtick` /
`bsrch` / `bqr` / `bcurves` / `bgovts` / the `xbbg.ext.*` helpers, plus
Bloomberg field overrides passed as `**kwargs` — now accepts
`datetime.date`, `datetime.datetime` (naive or tz-aware), and duck-typed
`pandas.Timestamp` in addition to strings. ISO 8601, `YYYYMMDD`, and
`"today"` strings continue to work; ambiguous `MM/DD/YYYY` inputs are
rejected with a clear `ValueError`. See the
[Dates and Datetimes guide](/python/guides/dates) for the full reference.
### BDIB before and after
::: details 0.x
```python
from xbbg import blp
bars = blp.bdib('AAPL US Equity', dt='2024-01-15', interval=5)
# pandas DataFrame indexed by datetime
# time open high low close volume
# 2024-01-15 09:30:00
```
:::
::: details 1.0 — semi\_long for OHLCV shape
```python
from xbbg import blp
# Default long format
bars = blp.bdib('AAPL US Equity', dt='2024-01-15', interval=5)
# long: ticker, time, field, value
# semi_long restores the OHLCV-per-row shape closest to 0.x
bars = blp.bdib('AAPL US Equity', dt='2024-01-15', interval=5,
format='semi_long')
# ticker time open high low close volume
# AAPL US Equity 2024-01-15 09:30:00 ... ... ... ... ...
```
:::
### Restoring wide output with pivot()
When downstream code requires the wide layout, apply `.pivot()` after the request. The exact
parameter names differ between backends:
```python
from xbbg import blp
# --- narwhals / Polars backend (default) ---
df = blp.bdp(['AAPL US Equity', 'MSFT US Equity'], ['PX_LAST', 'VOLUME'])
wide = df.pivot(on='field', index='ticker', values='value')
# BDH with narwhals / Polars
hist = blp.bdh('AAPL US Equity', ['open', 'high', 'low', 'close'],
'2024-01-01', '2024-01-31')
hist_wide = hist.pivot(on='field', index=['ticker', 'date'], values='value')
# --- pandas backend ---
df_pd = blp.bdp(['AAPL US Equity', 'MSFT US Equity'], ['PX_LAST', 'VOLUME'],
backend='pandas')
wide_pd = df_pd.pivot(columns='field', index='ticker', values='value')
```
### `format='semi_long'` — closest to old wide
`format='semi_long'` returns one row per ticker with each field as a column. For `bdp` this is the
shape closest to the 0.x default and is the smallest-effort migration:
```python
from xbbg import blp
df = blp.bdp(
['AAPL US Equity', 'MSFT US Equity'],
['PX_LAST', 'VOLUME'],
format='semi_long',
)
# ticker px_last volume
# AAPL US Equity
# MSFT US Equity
```
### Format reference
| Format | Shape | Supports lazy backends |
|--------|-------|------------------------|
| `long` (default) | `ticker, [date,] field, value` | Yes |
| `long_typed` | `ticker, [date,] field, value_f64, value_i64, …` | Yes |
| `long_with_metadata` | `ticker, [date,] field, value, dtype` | Yes |
| `semi_long` | `ticker, [date,]` then one column per field | Yes |
`Format.WIDE` was **removed**. Passing `format='wide'` raises `ValueError` — use `pivot()` or
`format='semi_long'` instead.
## Backend migration
### Before: pandas only
xbbg 0.x depended on pandas. Every function returned `pd.DataFrame`. No configuration was needed.
### After: narwhals default, pandas optional
xbbg 1.0 uses PyArrow for the on-the-wire data transport between Rust and Python, and narwhals
for the DataFrame construction layer. pandas is no longer pulled in automatically.
**Core dependencies** (installed with `pip install xbbg`):
* `narwhals >= 1.30`
* `pyarrow >= 22`
**Optional backends** (install separately as needed):
```bash
pip install pandas # pandas DataFrames
pip install polars # Polars DataFrames (eager and lazy)
pip install duckdb # DuckDB relations
```
### Restoring pandas globally
To make every xbbg call return a `pd.DataFrame` for an entire session, set the backend once at
the top of your script:
```python
from xbbg import set_backend
set_backend('pandas')
# All subsequent calls return pd.DataFrame
```
Or per-call:
```python
df = blp.bdp('AAPL US Equity', ['PX_LAST', 'VOLUME'], backend='pandas')
```
Combine with `format='semi_long'` to get the closest match to the 0.x default:
```python
df = blp.bdp('AAPL US Equity', ['PX_LAST', 'VOLUME'],
backend='pandas', format='semi_long')
```
### Inspecting available backends
```python
from xbbg import get_available_backends, print_backend_status
print(get_available_backends()) # e.g. ['narwhals', 'pyarrow', 'pandas']
print_backend_status() # installed/missing with version info
```
## Connection setup
`blp.connect()` and `blp.disconnect()` no longer exist. The engine starts automatically on the
first request. Call `xbbg.configure()` once before your first request only if you need a
non-default host, port, or authentication. Connecting to `localhost:8194` (the default Bloomberg
Terminal port) requires no `configure()` call at all.
::: details 0.x
```python
from xbbg import blp
blp.connect(host='192.168.1.100', port=18194)
df = blp.bdp('AAPL US Equity', 'PX_LAST')
blp.disconnect()
```
:::
::: details 1.0
```python
import xbbg
from xbbg import blp
# configure() replaces connect() — call once before first request
xbbg.configure(host='192.168.1.100', port=18194)
df = blp.bdp('AAPL US Equity', 'PX_LAST')
# No disconnect needed — engine lifecycle is managed automatically
```
:::
`xbbg.configure()` accepts every field on `EngineConfig`. The full list, with defaults, is in
the [configuration reference](/python/reference/configuration). The most common ones for migration
from 0.x are:
| Field | Default | Notes |
|-------|---------|-------|
| `host` | `"localhost"` | Bloomberg server hostname |
| `port` | `8194` | Bloomberg server port |
| `servers` | `None` | List of `(host, port)` tuples for failover; overrides `host`/`port` if set |
| `auth_method` | `None` | One of `"user"`, `"app"`, `"userapp"`, `"dir"`, `"manual"`, `"token"` (see below) |
| `app_name` | `None` | Required when `auth_method` is `"app"`, `"userapp"`, or `"manual"` |
| `user_id` | `None` | Required when `auth_method="manual"` |
| `ip_address` | `None` | Required when `auth_method="manual"` |
| `token` | `None` | Required when `auth_method="token"` |
| `dir_property` | `None` | Required when `auth_method="dir"` (Active Directory property name) |
| `request_pool_size` | `2` | Number of concurrent reference-data workers |
| `subscription_pool_size` | `1` | Number of concurrent subscription workers |
| `num_start_attempts` | (engine default) | Session retry count |
| `auto_restart_on_disconnection` | `True` | Auto-reconnect on disconnect |
`configure()` validates keyword arguments against the canonical `EngineConfig` field names
above and raises `TypeError` on unknown kwargs. The legacy xbbg 0.x aliases (`server_host`,
`server_port`, `max_attempt`, `auto_restart`, etc.) are no longer accepted — use the
canonical names listed above.
## Authentication, SAPI, and B-PIPE
xbbg 1.0 supports six authentication modes via `auth_method`. Each mode requires a specific set
of additional fields. The Rust engine wires these into the underlying `blpapi_AuthOptions` and
performs session authorization during startup; failures surface as `BlpSessionError` (or
`BlpBPipeError` for B-PIPE-specific failures) on the first request — they do not silently produce
empty results.
| `auth_method` | Required fields | Use case |
|---------------|-----------------|----------|
| `"user"` | *(none)* | OS logon name — typical desktop SAPI |
| `"app"` | `app_name` | Application authentication — a single named application |
| `"userapp"` | `app_name` | Combined OS logon + application |
| `"dir"` | `dir_property` | Active Directory property lookup |
| `"manual"` | `app_name`, `user_id`, `ip_address` | B-PIPE entitlement — application acting on behalf of a specific user |
| `"token"` | `token` | Pre-generated authorization token |
### B-PIPE manual authentication
```python
import xbbg
from xbbg import blp
xbbg.configure(
host='bpipe-host.internal',
port=8195,
auth_method='manual',
app_name='MyApp',
user_id='UserOnPlatform',
ip_address='10.0.0.42',
)
df = blp.bdp('SPX Index', 'PX_LAST')
```
### Application authentication (no per-user identity)
```python
import xbbg
xbbg.configure(
host='sapi-gateway.internal',
port=8194,
auth_method='app',
app_name='MyApp',
)
```
### Token authentication
```python
import xbbg
xbbg.configure(
auth_method='token',
token='',
)
```
### ZFP over leased lines
For ZFP (Zero Footprint) leased-line connections, pass `zfp_remote='8194'` or `zfp_remote='8196'` plus TLS credentials before the first request. xbbg uses Bloomberg's ZFP utility to populate the leased-line endpoints, so `zfp_remote` is mutually exclusive with `host`, `port`, `servers`, `socks5_host`, and `socks5_port`.
```python
import xbbg
xbbg.configure(
zfp_remote='8194',
tls_client_credentials='/secure/client.p12',
tls_client_credentials_password='secret',
tls_trust_material='/secure/trust.p7',
)
```
| Field | Type | Purpose |
|-------|------|---------|
| `zfp_remote` | `str` | ZFP leased-line remote, either `'8194'` or `'8196'` |
| `tls_client_credentials` | `str` | Path to client credentials file |
| `tls_client_credentials_password` | `str` | Password for the credentials file, if required |
| `tls_trust_material` | `str` | Path to the trusted-CA bundle |
| `tls_handshake_timeout_ms` | `int` | Optional TLS handshake timeout |
| `tls_crl_fetch_timeout_ms` | `int` | Optional CRL fetch timeout |
## Renamed and replaced functions
| 0.x | 1.0 | Notes |
|-----|-----|-------|
| `blp.connect(host, port, …)` | `xbbg.configure(host=…, port=…, …)` | Engine auto-starts; `configure()` is only needed for non-default settings |
| `blp.disconnect()` | *(none — automatic)* | The engine handles its own lifecycle. Use `xbbg.shutdown()` only if you need to force cleanup |
| `blp.getBlpapiVersion()` | `xbbg.get_sdk_info()` | Returns a `dict` with all detected SDK sources and their versions, plus `runtime_version` |
| `blp.fieldInfo(fields)` | `blp.bfld(fields=…)` | `fieldInfo` still works as an alias |
| `blp.fieldSearch(keyword)` | `blp.bfld(search_spec=keyword)` | Search merged into `bfld()` / `bflds()` |
| `blp.lookupSecurity(name)` | `blp.blkp(query, yellowkey='YK_FILTER_*')` | Renamed; **yellowkey format changed** — the legacy short codes are replaced by `YK_FILTER_NONE` / `YK_FILTER_CMDTY` / `YK_FILTER_EQTY` / `YK_FILTER_CRNCY` / etc. |
| `blp.getPortfolio(portfolio, …)` | `blp.bport(portfolio, fields, …)` | Renamed for consistency with other `b*` helpers |
| `blp.bta_studies(…)` | `blp.ta_studies(…)` | Renamed; the `_studies` shortcut is now the canonical name |
| `blp.refresh_studies(…)` | *(removed)* | No replacement |
| `blp.live(tickers, flds, …)` | `blp.stream(…)` / `blp.subscribe(…)` / `blp.asubscribe(…)` | The async generator returning `dict`s is gone. The new APIs return a `Subscription` object that yields DataFrames |
| `blp.subscribe(…)` (context manager) | `blp.subscribe(…)` / `blp.asubscribe(…)` | No longer a context manager. Returns a `Subscription` object with dynamic add/remove and DataFrame yielding |
### Parameter renames
| Function | 0.x parameter | 1.0 parameter |
|----------|---------------|---------------|
| `blp.beqs` | `typ` | `screen_type` |
### Request element aliases
xbbg 1.x accepts the 0.x Bloomberg request-element aliases before a request is sent to Bloomberg.
Aliases are normalized to canonical Bloomberg element names, and enum-like shorthand values are resolved using
the target element context (for example `Quote="C"` means `OVERRIDE_OPTION_CLOSE`, while `Fill="C"`
means `PREVIOUS_VALUE`).
| Aliases | Canonical request element | Value aliases |
|---------|---------------------------|---------------|
| `PeriodAdj`, `PerAdj` | `periodicityAdjustment` | `A` → `ACTUAL`, `C` → `CALENDAR`, `F` → `FISCAL` |
| `Period`, `Per` | `periodicitySelection` | `D`/`W`/`M`/`Q`/`S`/`Y` → `DAILY`/`WEEKLY`/`MONTHLY`/`QUARTERLY`/`SEMI_ANNUALLY`/`YEARLY` |
| `Currency`, `Curr`, `FX` | `currency` | — |
| `Days` | `nonTradingDayFillOption` | `N`, `W`, `Weekdays` → `NON_TRADING_WEEKDAYS`; `C`, `A`, `All` → `ALL_CALENDAR_DAYS`; `T`, `Trading` → `ACTIVE_DAYS_ONLY` |
| `Fill` | `nonTradingDayFillMethod` | `C`, `P`, `Previous` → `PREVIOUS_VALUE`; `B`, `Blank`, `NA` → `NIL_VALUE` |
| `Points` | `maxDataPoints` | — |
| `Quote` | `overrideOption` | `A`, `G`, `Average` → `OVERRIDE_OPTION_GPA`; `C`, `Close` → `OVERRIDE_OPTION_CLOSE` |
| `QuoteType`, `QtTyp` | `pricingOption` | `P`, `Price` → `PRICING_OPTION_PRICE`; `Y`, `Yield` → `PRICING_OPTION_YIELD` |
| `CshAdjNormal` | `adjustmentNormal` | — |
| `CshAdjAbnormal` | `adjustmentAbnormal` | — |
| `CapChg` | `adjustmentSplit` | — |
| `UseDPDF` | `adjustmentFollowDPDF` | — |
| `Calendar` | `calendarCodeOverride` | — |
| `BarSz`, `BarSize` | `interval` | integer minutes |
| `BarTp`, `BarType` | `eventType` / `event_types` | `B`, `Bid` → `BID`; `A`, `Ask` → `ASK`; `T`, `Trade` → `TRADE` |
| `IncludeExchangeCodes` | `includeExchangeCodes` | — |
The Excel-only presentation aliases do not have Bloomberg request-element equivalents. For `bdh()`,
xbbg consumes them locally and applies the output shaping after Bloomberg returns raw data:
| Aliases | Local option | Value aliases | Effect |
|---------|--------------|---------------|--------|
| `Dts`, `Dates` | `show_date` | `Show`, `S`, `True` → show; `Hide`, `H`, `False` → hide | Keep or remove the `date`/`period` columns |
| `DtFmt`, `DateFormat` | `date_format` | `D`, `Date` → `DATE`; `P`, `Periodic` → `PERIODIC`; `B`, `Both` → `BOTH` | Keep dates, replace dates with period labels, or include both |
| `Sort` | `sort` | `C`, `A`, `Ascend`, `Chronological`, `False` → ascending; `R`, `D`, `Descend`, `Reverse`, `True` → descending | Sort historical rows by date within ticker |
| `Orientation`, `Direction`, `Dir` | `orientation` | `V`, `Vertical` → vertical; `H`, `Horizontal` → horizontal | Select `format='long'` or `format='semi_long'` when no explicit `format` is passed |
## Functions moved to `xbbg.ext`
These helpers used to live on the top-level `xbbg.blp` module in 0.x. They have **moved** to
`xbbg.ext` in 1.0:
| 0.x | 1.0 |
|-----|-----|
| `blp.dividend(…)` | `xbbg.ext.dividend(…)` |
| `blp.earning(…)` | `xbbg.ext.earnings(…)` *(note plural)* |
| `blp.turnover(…)` | `xbbg.ext.turnover(…)` |
| `blp.adjust_ccy(…)` | `xbbg.ext.convert_ccy(…)` |
| `blp.fut_ticker(…)` | `xbbg.ext.fut_ticker(…)` |
| `blp.active_futures(…)` | `xbbg.ext.active_futures(…)` |
| `blp.cdx_ticker(…)` | `xbbg.ext.cdx_ticker(…)` |
| `blp.active_cdx(…)` | `xbbg.ext.active_cdx(…)` |
| `blp.etf_holdings(…)` | `xbbg.ext.etf_holdings(…)` |
| `blp.preferreds(…)` | `xbbg.ext.preferreds(…)` |
| `blp.corporate_bonds(…)` | `xbbg.ext.corporate_bonds(…)` |
| `blp.yas(…)` | `xbbg.ext.yas(…)` |
Migration is mechanical — change the import:
```python
# 0.x
from xbbg import blp
df = blp.dividend('AAPL US Equity', '2023-01-01', '2024-01-01')
# 1.0
from xbbg import ext
df = ext.dividend('AAPL US Equity', '2023-01-01', '2024-01-01')
```
`xbbg.ext` also adds new analytics that didn't exist in 0.x — bonds (`bond_info`, `bond_curve`,
`bond_cashflows`, `bond_risk`, …), CDX (`cdx_pricing`, `cdx_curve`, …), and options. Each function
has an `a*`-prefixed async variant.
## Removals
### `Format.WIDE`
Removed. Passing `format='wide'` raises `ValueError`. Use `format='semi_long'` or `pivot()`.
### `asset_config()`
Removed. In 0.12.x this already returned an empty DataFrame and was deprecated. Use
`xbbg.markets.market_info(ticker)` to retrieve exchange code, timezone, and futures-cycle
metadata directly from Bloomberg:
```python
from xbbg.markets import market_info
info = market_info('ES1 Index')
# pd.Series with 'exch', 'tz', session times, and related fields
```
### `refresh_studies()`
Removed. No direct replacement — recompute by issuing a fresh `bta()` call.
## Async migration
Every reference, historical, intraday, screening, and TA function has an `a`-prefixed async
variant: `abdp`, `abdh`, `abdib`, `abdtick`, `abds`, `abql`, `absrch`, `abeqs`, `ablkp`, `abport`,
`abfld` / `abflds`, `abqr`, `abta`, etc. The same names existed in 0.x — but in 0.x they wrapped
synchronous blpapi calls in a thread pool and held the GIL. In 1.0 they are backed by a true
async Rust engine that releases the GIL for the duration of the request.
The migration is "do nothing" — the same code keeps working — but it is now actually concurrent:
```python
import asyncio
from xbbg import blp
async def fetch_all():
return await asyncio.gather(
blp.abdp('SPX Index', 'PX_LAST'),
blp.abdp('NDX Index', 'PX_LAST'),
blp.abdp('INDU Index', 'PX_LAST'),
)
results = asyncio.run(fetch_all())
# Three Bloomberg requests issued in parallel against the engine's request pool.
```
The size of the request worker pool is controlled by `EngineConfig.request_pool_size` (default
`2`); subscriptions use a separate `subscription_pool_size`. Increase these if you have many
concurrent in-flight requests.
## Request validation, field metadata, and other 1.0-only options
xbbg 1.0 adds several per-request and per-engine options that have no 0.x equivalent. They are
designed to catch problems locally instead of round-tripping bad input to Bloomberg, and to give
you finer control over how the engine resolves field types and reports per-security failures.
### Engine-level field validation (`validation_mode`)
The Rust engine can validate every field against Bloomberg's field metadata catalog before the
request is dispatched. There are three modes, controlled by `EngineConfig.validation_mode`:
| Mode | Behavior |
|------|----------|
| `"disabled"` (default) | Skip validation entirely. Fastest path; matches 0.x behavior |
| `"lenient"` | Validate, log a warning for unknown fields, but still send the request |
| `"strict"` | Raise `BlpValidationError` on unknown fields before sending the request |
```python
import xbbg
xbbg.configure(validation_mode='strict')
# Now this raises BlpValidationError immediately — no network round-trip
df = xbbg.bdp('AAPL US Equity', 'PX_LSAT') # typo in PX_LAST
```
### Per-request validation override (`validate_fields`)
Every reference / historical / intraday function accepts a per-call `validate_fields` argument
that overrides the engine-level mode for one request only:
| Value | Effect |
|-------|--------|
| `None` (default) | Follow `EngineConfig.validation_mode` |
| `True` | Force strict validation for this request |
| `False` | Disable validation for this request |
```python
# Engine is in 'disabled' mode but you want strict checking on this one call
df = blp.bdp('AAPL US Equity', ['PX_LAST', 'VOLUME'], validate_fields=True)
```
### Field metadata cache (`field_cache_path`)
Field validation, type resolution, and `bfld` / `bflds` lookups all consult a local field
metadata cache at `~/.xbbg/field_cache.json` by default. The first lookup of an unknown field
populates the cache from `//blp/apiflds`; subsequent calls are zero-network. Override the
location with `EngineConfig.field_cache_path`:
```python
xbbg.configure(field_cache_path='/var/cache/fields.json')
```
This was previously not exposed at all in 0.x, which made every request re-resolve fields
through the C SDK.
### Manual type overrides (`field_types`)
`bdp` and `bdh` accept a `field_types` dict that forces specific fields to be returned as a
specific Arrow / numpy type, bypassing the type-inference path. Useful when Bloomberg's metadata
disagrees with what you actually want — e.g., forcing a string field to integer:
```python
df = blp.bdp(
'AAPL US Equity',
['PX_LAST', 'VOLUME'],
field_types={'VOLUME': 'int64'},
)
```
When `field_types` is `None` (the default), types are auto-resolved from the field cache.
### Surface per-security failures (`include_security_errors`)
In 0.x, when Bloomberg rejected a security inside a multi-ticker request, that ticker was
silently dropped from the response. In 1.0 you can surface those failures explicitly:
```python
df = blp.bdp(
['AAPL US Equity', 'NOT_A_TICKER'],
'PX_LAST',
include_security_errors=True,
)
# Includes a row with field '__SECURITY_ERROR__' for NOT_A_TICKER
```
Combined with the typed exception hierarchy, this means malformed inputs are easy to detect
without comparing the response shape against the request shape.
### Warm-up services (`warmup_services`)
The engine pre-warms a list of Bloomberg services at startup so the first real request doesn't
pay the connection-cold-start cost. The default is `["//blp/refdata", "//blp/apiflds"]`. Add
extra services if your workload always starts with, say, intraday bars or screening:
```python
xbbg.configure(warmup_services=[
'//blp/refdata',
'//blp/apiflds',
'//blp/exrsvc', # for bdh
'//blp/srcref', # for bsrch / beqs
])
```
## Error handling
In 0.x, errors were typically generic `RuntimeError`s, and several failure modes (notably
authorization failures during session startup) silently produced empty results. In 1.0 every
error has a typed exception class:
| Class | When it raises |
|-------|----------------|
| `BlpErrorBase` | Base class for every xbbg-originated exception |
| `BlpSessionError` | Session startup, authentication, or session-level failures |
| `BlpBPipeError` | B-PIPE-specific session/auth failures |
| `BlpRequestError` | Request-level failure (malformed request, service unavailable, etc.) |
| `BlpFieldError` | Per-field failure inside a request (subclass of `BlpRequestError`) |
| `BlpSecurityError` | Per-security failure inside a request (subclass of `BlpRequestError`) |
| `BlpValidationError` | Local validation of inputs failed before sending the request |
| `BlpTimeoutError` | Request exceeded the configured timeout |
| `BlpInternalError` | Unexpected internal engine error (please report) |
```python
from xbbg import blp
from xbbg.exceptions import BlpSessionError, BlpRequestError, BlpValidationError
try:
df = blp.bdp('AAPL US Equity', 'PX_LAST')
except BlpSessionError as e:
# Authentication / session failures land here
log.error("Bloomberg session failed: %s", e)
except BlpRequestError as e:
# The request reached Bloomberg but the response was an error
log.error("Bloomberg request failed: %s", e)
except BlpValidationError as e:
# Local validation rejected the request before sending
log.error("Invalid request: %s", e)
```
To catch any xbbg-originated error, use `BlpErrorBase`:
```python
from xbbg.exceptions import BlpErrorBase
try:
df = blp.bdp(tickers, fields)
except BlpErrorBase as e:
log.exception("xbbg failure")
raise
```
## Middleware and observability
xbbg 1.0 exposes a public middleware API around every reference, historical, and intraday
request. Middleware are async callables that wrap the request pipeline; they have full access to
the request context before and after the engine call, can mutate metadata, can raise to abort,
and compose like ASGI / Express middleware.
This is the supported integration point for telemetry, structured logging, OpenTelemetry spans,
per-request metrics, request authorization, and dynamic parameter rewriting.
### Registering middleware
```python
import time
from xbbg import blp
async def logging_middleware(context, call_next):
started = time.perf_counter()
try:
result = await call_next(context)
except Exception:
elapsed = (time.perf_counter() - started) * 1000
log.exception("xbbg request %s failed after %.1fms", context.request_id, elapsed)
raise
elapsed = (time.perf_counter() - started) * 1000
log.info(
"xbbg request %s ok: %d securities × %d fields → %d rows in %.1fms",
context.request_id,
len(context.securities),
len(context.fields),
context.batch.num_rows if context.batch is not None else 0,
elapsed,
)
return result
blp.add_middleware(logging_middleware)
# Use add_middleware as a decorator if you prefer:
@blp.add_middleware
async def trace_middleware(context, call_next):
return await call_next(context)
```
The full middleware management API:
| Function | Purpose |
|----------|---------|
| `blp.add_middleware(mw)` | Append a middleware to the chain. Usable as a decorator |
| `blp.remove_middleware(mw)` | Remove a previously registered middleware |
| `blp.clear_middleware()` | Drop all middleware |
| `blp.get_middleware()` | Inspect the current chain (returns a tuple) |
| `blp.set_middleware([mw1, mw2, …])` | Replace the entire chain in one call |
Middleware must be `async`. They are invoked once per top-level `bdp` / `bdh` / `bdib` / `abdp` /
etc. call, and run in registration order. Each middleware receives `(context, call_next)` and
must `await call_next(context)` to invoke the next stage in the pipeline (or the engine itself
if it's the last middleware).
### `RequestContext` fields
The `context` object passed through the middleware chain is a mutable dataclass-like container.
Every field listed below is populated before user middleware runs:
| Field | Type | Notes |
|-------|------|-------|
| `request_id` | `str` | Unique ID like `req-1776071581054356000`, useful as a correlation key |
| `params` | `RequestParams` | Parsed positional + keyword arguments to the original call |
| `params_dict` | `dict[str, Any]` | Raw kwargs dict |
| `backend` | `Backend \| str \| None` | Resolved backend (after applying defaults) |
| `securities` | `list[str]` | Normalized ticker list |
| `fields` | `list[str]` | Normalized field list |
| `environment` | `RequestEnvironment` | Snapshot of host / port / auth\_method / etc. for this call |
| `metadata` | `dict[str, Any]` | Mutable bag for user middleware to attach extra context (request tags, span IDs, …) |
| `started_at` | `float` | `time.perf_counter()` at middleware-chain entry |
| `elapsed_ms` | `float \| None` | Populated after the engine call returns |
| `batch` | `pa.RecordBatch \| None` | Raw Arrow batch from the engine, populated after the engine call |
| `table` | `pa.Table \| None` | Optional Arrow table form |
| `frame` | *backend frame* `\| None` | Final converted DataFrame (pandas, polars, narwhals, etc.) |
| `error` | `Exception \| None` | Set when middleware downstream raises |
### OpenTelemetry example
```python
from opentelemetry import trace
from xbbg import blp
tracer = trace.get_tracer("xbbg")
@blp.add_middleware
async def otel_middleware(context, call_next):
with tracer.start_as_current_span("xbbg.request") as span:
span.set_attribute("xbbg.request_id", context.request_id)
span.set_attribute("xbbg.host", context.environment.host)
span.set_attribute("xbbg.securities", len(context.securities))
span.set_attribute("xbbg.fields", len(context.fields))
try:
result = await call_next(context)
except Exception as exc:
span.record_exception(exc)
span.set_status(trace.Status(trace.StatusCode.ERROR))
raise
span.set_attribute("xbbg.rows", context.batch.num_rows if context.batch else 0)
span.set_attribute("xbbg.elapsed_ms", context.elapsed_ms or 0.0)
return result
```
Middleware is the right granularity for per-request telemetry. Per-ticker and per-field
fan-in/fan-out is not currently exposed as a separate hook — the engine deduplicates and batches
internally — but `context.securities` / `context.fields` give you the dimensions you need for
labelled metrics.
## Logging and tracing
### Python loggers
xbbg uses the standard `logging` module under the `xbbg.*` namespace:
| Logger | What it covers |
|--------|----------------|
| `xbbg` | Parent logger for the package |
| `xbbg.blp` | Request pipeline, middleware dispatch, backend resolution |
| `xbbg.backend` | Backend selection and availability checks |
| `xbbg.markets.bloomberg`, `xbbg.markets.overrides`, `xbbg.markets.info` | Market metadata lookups |
| `xbbg.ext.*` | Extension modules (bonds, options, cdx, futures, currency, historical) |
Enable debug output with the standard incantation:
```python
import logging
logging.basicConfig(level=logging.INFO)
logging.getLogger('xbbg').setLevel(logging.DEBUG)
```
### Rust tracing
The Rust core uses the `tracing` crate. Logging targets (`xbbg_core`, `xbbg_async`, `xbbg_log`,
`pyo3_xbbg`, …) can be controlled via the standard `RUST_LOG` environment variable:
```bash
RUST_LOG=xbbg_async=debug,xbbg_core=info python my_script.py
```
xbbg also exposes Python-side helpers to set / get the global Rust log level without process
restart (`xbbg.set_log_level('debug')`, `xbbg.get_log_level()`). These are atomic and contention-
free; safe to call from request paths.
## Step-by-step upgrade
1. **Upgrade the package and the Bloomberg Python wheel**
```bash
pip install --upgrade xbbg blpapi --extra-index-url https://blpapi.bloomberg.com/repository/releases/python/simple/
```
Make sure `blpapi` resolves to `>= 3.25` and you are on xbbg `>= 1.0.1` (1.0.0 has a known
`libblpapi` discovery bug on macOS / Linux fixed in 1.0.1).
2. **Verify the engine loads**
```python
import xbbg
info = xbbg.get_sdk_info()
print(info['active'], info['runtime_version'])
```
If this raises `ImportError`, see the install notes above — on 1.0.1+ you should not need
any `LD_LIBRARY_PATH` setup.
3. **Install whichever DataFrame backend you actually use**
```bash
pip install pandas # if your code returns / consumes pd.DataFrame
pip install polars # if you want polars
```
4. **Set a session-wide backend default if your code expects one**
```python
from xbbg import set_backend
set_backend('pandas')
```
5. **Remove `connect()` / `disconnect()` calls**
Delete every `blp.connect(...)` and `blp.disconnect()`. If you were passing a non-default
`host` / `port` / auth, replace those calls with a single `xbbg.configure(...)` call before
your first request using the canonical `EngineConfig` field names (`host`, `port`,
`num_start_attempts`, `auto_restart_on_disconnection`, etc.).
6. **Migrate B-PIPE / SAPI auth call sites**
Look at the [authentication section](#authentication-sapi-and-b-pipe) for the six supported
`auth_method` values and the required fields for each. The most common B-PIPE migration is
`auth_method='manual'` with `app_name`, `user_id`, and `ip_address`. Auth failures now raise
`BlpSessionError` / `BlpBPipeError` on the first request — they don't silently produce empty
results, so add explicit `try` / `except` for graceful degradation if you need it.
7. **Pick an output-format strategy**
The smallest-effort migration is to add `format='semi_long'` to each `bdp` and `bdib` call
(one row per ticker, fields as columns). For `bdh`, follow each call with
`.pivot(on='field', index=['ticker', 'date'], values='value')` if you need the old
MultiIndex shape.
The recommended longer-term path is to migrate downstream code to long format — it composes
directly with `groupby` / `merge` / filter operations and is the natural shape for
Arrow-backed pipelines.
8. **Update extension function imports**
`dividend`, `earning(s)`, `turnover`, `adjust_ccy` (now `convert_ccy`), `etf_holdings`,
`preferreds`, `corporate_bonds`, `yas`, `fut_ticker`, `active_futures`, `cdx_ticker`,
`active_cdx` — all moved from `xbbg.blp` to `xbbg.ext`. Change the import:
```python
from xbbg import ext
ext.dividend('AAPL US Equity', '2023-01-01', '2024-01-01')
```
9. **Replace deprecated function names**
* `blp.connect` / `blp.disconnect` → `xbbg.configure` (or remove entirely)
* `blp.getBlpapiVersion` → `xbbg.get_sdk_info`
* `blp.lookupSecurity` → `blp.blkp` (note the new `YK_FILTER_*` yellowkey format)
* `blp.getPortfolio` → `blp.bport`
* `blp.fieldInfo` / `blp.fieldSearch` → `blp.bfld` / `blp.bflds` (legacy names also work)
* `blp.bta_studies` → `blp.ta_studies`
* `beqs(typ=…)` → `beqs(screen_type=…)`
* `blp.live(…)` / `blp.subscribe(…)` (context manager) → `blp.stream(…)` / `blp.asubscribe(…)`
returning a `Subscription`
10. **Wrap in error handling**
Catch `BlpSessionError` (auth / session) and `BlpRequestError` (per-request failure) at the
edge of your data-fetching code rather than the old generic `RuntimeError`. See
[Error handling](#error-handling).
11. **Add observability if you need it**
Register a middleware via `blp.add_middleware(...)` for structured logging, OpenTelemetry
spans, or per-request metrics. See [Middleware and observability](#middleware-and-observability)
for the canonical pattern.
## Further reading
* [Output Formats](/python/guides/output-formats) — full format reference with column-level examples
* [DataFrame Backends](/python/guides/backends) — backend selection, lazy backends, performance
* [Async Patterns](/python/guides/async) — async usage, concurrency, cancellation
* [Configuration Reference](/python/reference/configuration) — every `EngineConfig` field with defaults
* [API Reference](/python/api/blp) — complete function signatures and parameter documentation
---
---
url: 'https://xbbg.org/javascript/api/surface.md'
description: Public @xbbg/core TypeScript and JavaScript surface from the package source
---
## Runtime and configuration
## Constants, helpers, and errors
Error exports include `BlpError`, `BlpSessionError`, `BlpRequestError`, `BlpValidationError`, `BlpTimeoutError`, `BlpInternalError`, and `wrapError`.
## Top-level request helpers
| Family | Helpers |
|--------|---------|
| Reference / historical / bulk | `bdp`, `abdp`, `bdh`, `abdh`, `bds`, `abds` |
| Intraday | `bdib`, `abdib`, `bdtick`, `abdtick` |
| Subscriptions | `subscribe`, `asubscribe`, `Subscription`, `Tick`, `ArrowSubscription` |
| Namespaces | `blp`, `ext` |
The top-level helpers use the configured engine. They are convenient for services that want one process-level runtime.
## Engine methods
`Engine` exposes the full request and operational surface:
| Area | Methods |
|------|---------|
| Generic execution | `request`, `requestRaw` |
| Core Bloomberg workflows | `bdp`, `bds`, `bdh`, `bdib`, `bdtick`, `bql`, `beqs`, `bsrch`, `bta`, `bflds`, `blkp`, `bport`, `bcurves`, `bgovts` |
| Field metadata | `resolveFieldTypes`, `getFieldInfo`, `clearFieldCache`, `saveFieldCache`, `validateFields`, `isFieldValidationEnabled` |
| Schema introspection | `getSchema`, `getOperation`, `listOperations`, `getCachedSchema`, `invalidateSchema`, `clearSchemaCache`, `listCachedSchemas`, `getEnumValues`, `listValidElements`, `bops`, `bschema` |
| Streaming services | `subscribe`, `subscribeWithOptions`, `stream`, `vwap`, `mktbar`, `depth`, `chains` |
| Lifecycle | `signalShutdown`, `isAvailable` |
## Recipe and analytics methods
| Area | Methods |
|------|---------|
| Fixed income | `bqr`, `yas`, `preferreds`, `corporateBonds` |
| Futures / CDX resolution | `futTicker`, `activeFutures`, `cdxTicker`, `activeCdx` |
| Historical / holdings | `dividend`, `turnover`, `etfHoldings` |
| Currency | `currencyConversion` |
## `blp` namespace
The `blp` namespace exposes the common Bloomberg request helpers in an object shape:
```ts
import { blp } from '@xbbg/core';
const snapshot = await blp.abdp(['AAPL US Equity'], ['PX_LAST']);
const history = await blp.abdh(['AAPL US Equity'], ['PX_LAST'], '2024-01-01', '2024-01-31');
const sub = await blp.asubscribe(['AAPL US Equity'], ['LAST_PRICE']);
```
Current `blp` keys include `bdp`, `bdh`, `bds`, `bdib`, `bdtick`, `subscribe`, `abdp`, `abdh`, `abds`, `abdib`, `abdtick`, and `asubscribe`.
## `ext` namespace
The `ext` namespace exposes lower-level helpers and native utility functions for recipes and market metadata:
* CDX helpers: `ext.cdx.acdx_info`, `ext.cdx.acdx_pricing`, `ext.cdx.acdx_risk`
* Date and format helpers: `parseDate`, `fmtDate`, `pivotToWide`, `isLongFormat`
* Ticker and futures helpers: `parseTicker`, `buildFuturesTicker`, `generateFuturesCandidates`, `validateGenericTicker`, `filterValidContracts`
* CDX ticker helpers: `parseCdxTicker`, `previousCdxSeries`, `cdxGenToSpecific`
* Currency helpers: `buildFxPair`, `sameCurrency`, `currenciesNeedingConversion`
* Historical and holdings helpers: `renameDividendColumns`, `renameEtfColumns`, `getDvdTypes`, `getDvdCols`, `getEtfCols`
* Fixed-income query helpers: `buildYasOverrides`, `buildPreferredsQuery`, `buildCorporateBondsQuery`
* Market/session helpers: `deriveSessions`, `getMarketRule`, `inferTimezone`, exchange override helpers, `sessionTimesToUtc`
## Public TypeScript types
The package exports typed inputs for every public surface, including `DateLike`, `DateTimeLike`, `EngineConfig`, `RequestInput`, `StreamOptions`, `BdpOptions`, `BdhOptions`, `BdibOptions`, `BdtickOptions`, `BqlOptions`, `BeqsOptions`, `BsrchOptions`, `BtaOptions`, `BfldsOptions`, `BqrOptions`, `YasOptions`, `PreferredsOptions`, `CorporateBondsOptions`, `FuturesResolveOptions`, `ActiveCdxOptions`, `DividendOptions`, `TurnoverOptions`, `EtfHoldingsOptions`, `RetryPolicy`, `TlsConfig`, `Socks5Config`, and result metadata interfaces such as `SubscriptionStats`, `FieldInfo`, `ExchangeInfoResult`, and `SessionWindowsInfo`.
## Backend notes
* `Backend.ARROW` returns Apache Arrow tables.
* `Backend.JSON` returns JavaScript-friendly objects.
* `Backend.POLARS` requires the optional `nodejs-polars` peer dependency.
* `DateLike` accepts `Date`, ISO/Bloomberg-native strings, epoch milliseconds, or duck-typed Luxon `DateTime` values with `toJSDate()`.
---
---
url: 'https://xbbg.org/python/guides/output-formats.md'
description: 'Control output shape with Format.LONG, LONG_TYPED, and more'
---
xbbg returns data in a tidy long format by default. The `format` parameter on any data function lets you select a different shape. Pass a `Format` enum value or its string equivalent.
```python
from xbbg import blp, Format
df = blp.bdp('AAPL US Equity', ['PX_LAST', 'VOLUME'], format=Format.LONG_TYPED)
# or equivalently
df = blp.bdp('AAPL US Equity', ['PX_LAST', 'VOLUME'], format='long_typed')
```
## Quick Reference
| Format | String alias | Columns | Use case |
|---|---|---|---|
| `Format.LONG` | `'long'` | ticker, field, value | Default. Joins, aggregations, tidy data |
| `Format.LONG_TYPED` | `'long_typed'` | ticker, field, value\_f64, value\_i64, value\_str, value\_date, value\_ts, value\_bool | Type-safe analysis without casting |
| `Format.LONG_WITH_METADATA` | `'long_metadata'` | ticker, field, value, dtype | Serialization, debugging, data catalogs |
| `Format.SEMI_LONG` | `'semi_long'` | ticker (+ date for bdh), one column per field | Quick inspection, closest to wide behavior |
::: info
Lazy backends (Polars lazy, narwhals lazy, SQLFrame) support `LONG`, `SEMI_LONG`, `LONG_TYPED`, and `LONG_WITH_METADATA`.
:::
---
## Format.LONG (default)
All field values are returned as strings. This is the default and is backwards-compatible with all backends.
**Columns:** `ticker`, `field`, `value`
```python
from xbbg import blp
df = blp.bdp(
['AAPL US Equity', 'MSFT US Equity'],
['PX_LAST', 'VOLUME'],
)
```
```
ticker field value
0 AAPL US Equity PX_LAST 189.30
1 AAPL US Equity VOLUME 58234100.0
2 MSFT US Equity PX_LAST 415.12
3 MSFT US Equity VOLUME 22183400.0
```
Because `value` is always a string, downstream code that needs numeric types must cast explicitly. This is intentional: LONG makes no assumptions about the field type, so it works correctly regardless of Bloomberg's metadata for a field.
**Best for:** tidy-data workflows, `groupby`/`join` operations, writing to columnar stores, passing data to ML pipelines that apply their own type inference.
***
## Format.LONG\_TYPED
Each row is placed in the value column matching its Arrow type. Unmatched columns are null for that row. No casting is required by callers.
**Columns:** `ticker`, `field`, `value_f64`, `value_i64`, `value_str`, `value_bool`, `value_date`, `value_ts`
```python
from xbbg import blp, Format
df = blp.bdp(
['AAPL US Equity', 'MSFT US Equity'],
['PX_LAST', 'VOLUME', 'SECURITY_NAME'],
format=Format.LONG_TYPED,
)
```
```
ticker field value_f64 value_i64 value_str value_bool value_date value_ts
0 AAPL US Equity PX_LAST 189.30 null null null null null
1 AAPL US Equity VOLUME null 58234100 null null null null
2 AAPL US Equity SECURITY_NAME null null Apple Inc null null null
3 MSFT US Equity PX_LAST 415.12 null null null null null
4 MSFT US Equity VOLUME null 22183400 null null null null
5 MSFT US Equity SECURITY_NAME null null Microsoft Co null null null
```
Field types come from Bloomberg's field metadata and are resolved at query time. You can override the type for specific fields with `field_types`:
```python
df = blp.bdp(
'AAPL US Equity',
['PX_LAST', 'VOLUME'],
format=Format.LONG_TYPED,
field_types={'VOLUME': 'float64'}, # treat VOLUME as f64 instead of i64
)
```
**Best for:** type-safe downstream analysis, Arrow/Parquet pipelines, anything where you need to branch on numeric vs. string values without inspecting dtype metadata at runtime.
***
## Format.LONG\_WITH\_METADATA
Like `LONG`, but adds a `dtype` column containing the Arrow type name for each value. The `value` column is still a string.
**Columns:** `ticker`, `field`, `value`, `dtype`
```python
from xbbg import blp, Format
df = blp.bdp(
['AAPL US Equity', 'MSFT US Equity'],
['PX_LAST', 'VOLUME', 'SECURITY_NAME'],
format=Format.LONG_WITH_METADATA,
)
```
```
ticker field value dtype
0 AAPL US Equity PX_LAST 189.30 float64
1 AAPL US Equity VOLUME 58234100 int64
2 AAPL US Equity SECURITY_NAME Apple Inc string
3 MSFT US Equity PX_LAST 415.12 float64
4 MSFT US Equity VOLUME 22183400 int64
5 MSFT US Equity SECURITY_NAME Microsoft Co string
```
The `dtype` values are Arrow type names: `float64`, `int64`, `string`, `bool`, `date32`, `timestamp[us]`. These are stable across backends.
**Best for:** serialization to JSON/CSV where typed columns are not available, debugging unexpected type resolutions, building data catalogs that track field-level types.
***
## Format.SEMI\_LONG
One row per ticker (for `bdp`) or per ticker/date (for `bdh`). Fields become columns. Values are typed according to each field's Bloomberg metadata.
**Columns (bdp):** `ticker`, then one column per requested field\
**Columns (bdh):** `ticker`, `date`, then one column per requested field
```python
from xbbg import blp, Format
# Reference data
df = blp.bdp(
['AAPL US Equity', 'MSFT US Equity'],
['PX_LAST', 'VOLUME', 'SECURITY_NAME'],
format=Format.SEMI_LONG,
)
```
```
ticker PX_LAST VOLUME SECURITY_NAME
0 AAPL US Equity 189.30 58234100 Apple Inc
1 MSFT US Equity 415.12 22183400 Microsoft Co
```
```python
# Historical data
df = blp.bdh(
'SPX Index',
['PX_LAST', 'PX_VOLUME'],
'2024-01-02',
'2024-01-05',
format=Format.SEMI_LONG,
)
```
```
ticker date PX_LAST PX_VOLUME
0 SPX Index 2024-01-02 4742.83 2134500000
1 SPX Index 2024-01-03 4704.81 2011800000
2 SPX Index 2024-01-04 4697.24 2198200000
3 SPX Index 2024-01-05 4697.24 1834600000
```
SEMI\_LONG retains the `ticker` column as an identifier rather than pivoting tickers into column headers. Multi-ticker queries produce stacked rows, not expanded columns.
**Best for:** quick visual inspection, passing to charting libraries, situations where you want named field columns but not a fully pivoted multi-ticker layout.
## Excel presentation aliases for `bdh()`
`bdh()` also accepts the Excel-style presentation aliases from the Bloomberg add-in. These are not sent to Bloomberg; xbbg applies them locally after the raw historical response returns.
| Alias family | Values | Effect |
|--------------|--------|--------|
| `Dts`, `Dates`, `show_date` | `Show`/`S`/`True`, `Hide`/`H`/`False` | Keep or remove date-style columns |
| `DtFmt`, `DateFormat`, `date_format` | `D`/`Date`, `P`/`Periodic`, `B`/`Both` | Use date labels, period labels, or both |
| `Sort`, `sort` | `A`/`Ascend`/`Chronological`, `R`/`Reverse`/`Descend` | Sort historical rows by date |
| `Orientation`, `Direction`, `Dir`, `orientation` | `V`/`Vertical`, `H`/`Horizontal` | Select long or semi-long output when `format=` is not explicit |
```python
hist = blp.bdh(
'SPX Index',
'PX_LAST',
'2024-01-01',
'2024-12-31',
Per='M',
DtFmt='Both',
Sort='Reverse',
Direction='H',
)
```
Explicit `format=` still wins over `Direction`/`Orientation`; use the alias only when you want Excel-like call sites to choose the default shape.
***
***
## Which Format to Choose
::: info LONG
You are doing joins, groupby, or aggregations. You need maximum backend compatibility. You will cast values yourself or don't need typed access.
:::
::: info LONG\_TYPED
You need typed numeric/string/date values without writing casts. You are writing to Parquet or Arrow. You branch logic on value type.
:::
::: info LONG\_WITH\_METADATA
You need to know the Arrow type of each value alongside its string representation. Useful for serialization layers and debug workflows.
:::
::: info SEMI\_LONG
You want fields as columns for immediate inspection or charting. Multi-ticker output is acceptable as stacked rows.
:::
When in doubt, use the default (`LONG`). It is stable, backend-agnostic, and the easiest to reason about. Promote to `LONG_TYPED` when type safety is required, or to `SEMI_LONG` when a column-per-field layout simplifies downstream code.
### Setting a session-wide default
If all calls in your script should use the same format, pass `format` to each call rather than relying on a global — it keeps each call self-documenting. For exploratory work, the string aliases are concise:
```python
from xbbg import blp
df = blp.bdp('AAPL US Equity', ['PX_LAST', 'VOLUME', 'SECURITY_NAME'], format='long_typed')
df = blp.bdh('SPX Index', 'PX_LAST', '2024-01-01', '2024-12-31', format='semi_long')
```
---
---
url: 'https://xbbg.org/overview/package-map.md'
description: How the xbbg Python and Node.js packages share one Rust/Arrow engine
---
## Public surfaces
| Package | Ecosystem | Registry | Install | Best fit |
|---------|-----------|----------|---------|----------|
| `xbbg` | Python / PyPI | [PyPI](https://pypi.org/project/xbbg/) | `pip install xbbg` | Python notebooks, research jobs, data pipelines, and services |
| `@xbbg/core` | Node.js / npm | [npm](https://www.npmjs.com/package/@xbbg/core) | `npm install @xbbg/core` | Node.js services that need matching Bloomberg-data behavior |
## What stays shared
## Implementation details
The platform-specific npm packages used by `@xbbg/core`, Rust crates, binding crates, and private monorepo packages are implementation details. Public docs stay centered on the installable packages users choose directly.
## Next steps
* [Python docs](/python/) — use the shared engine from Python
* [JavaScript docs](/javascript/) — use the shared engine from Node.js
* [Architecture / Shared Engine](/overview/architecture/) — see the request path
* [Release notes](/releases/changelog/) — track behavior and API changes
---
---
url: 'https://xbbg.org/javascript/api/core/interfaces/preferredsoptions.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:256`)
## Properties
### backend?
> `optional` **backend?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:258`)
***
### fields?
> `optional` **fields?**: `string`\[]
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:257`)
---
---
url: 'https://xbbg.org/python.md'
description: Public documentation for the xbbg Python package
---
## Start here
## Why xbbg is different
Many Python Bloomberg-data packages wrap Bloomberg's `blpapi` Python bindings directly. That can be enough for small scripts, but production workflows still have to decide where session lifecycle, event parsing, concurrency, diagnostics, middleware, enterprise connectivity, and output conversion live.
xbbg puts those concerns behind a native Rust/Arrow engine that integrates with the Bloomberg C/C++ SDK, manages sessions and worker pools, builds typed Arrow output, and exposes enterprise transports such as ZFP over leased lines, B-PIPE/SAPI auth, TLS, failover servers, SOCKS5, SDK logging, validation, request diagnostics, and request middleware.
## API families
| Family | Helpers | Use when |
|--------|---------|----------|
| Reference / historical / bulk | `bdp`, `bdh`, `bds`, `bdib`, `bdtick` and async variants | Core market-data retrieval |
| Search and services | `bql`, `beqs`, `bsrch`, `bqr`, `bflds`, generic requests | Bloomberg service workflows beyond simple field pulls |
| Streaming | `subscribe`, `asubscribe`, streaming helpers | Realtime data with subscription diagnostics |
| Fixed income | `bqr`, `bcurves`, `bgovts`, `yas`, `corporate_bonds`, bond helpers | Quotes, curves, government securities, yield/risk analytics, and cashflows |
| Operations | `configure`, middleware management, logging, backend configuration | Production setup and observability |
## Enterprise middleware
xbbg includes request middleware for teams that need platform-wide controls around Bloomberg access. Middleware receives request context and environment snapshots, so one shared pipeline can add audit logging, request IDs, metrics, tracing, entitlement checks, policy enforcement, standardized error handling, and compliance hooks without wrapping every individual `bdp()`, `bdh()`, `bql()`, or streaming call.
## Compared with other Bloomberg Python wrappers
xbbg is a Python ergonomic layer on top of a Rust engine backed by Bloomberg C/C++ SDK integration, with a matching Node.js surface on the same core. That distinction matters once a workflow grows beyond a single `bdp()` call.
* **Raw `blpapi`** is official but low-level: every application has to rebuild session startup, service opening, request construction, correlation IDs, event-loop parsing, error mapping, retries, logging, and dataframe conversion. xbbg keeps SDK access underneath while adding typed helpers, generic service requests, structured errors, async execution, and Arrow-native output.
* **bbg-fetch / BloombergFetch** is a Python pandas helper package. It targets Python 3.9–3.12, installs NumPy and pandas as hard dependencies, and does not cover intraday bars, ticks, streaming, BQL, BEQS, BSRCH, BQR, BTA, ZFP, B-PIPE/SAPI auth, SDK logging, multi-backend output, typed Arrow transport, async execution, or generic Bloomberg service requests.
* **pdblp** is a legacy pandas-era wrapper and is explicitly superseded by `blp`; it has no modern `Requires-Python` floor, depends on old pandas-era assumptions, and is not under active development.
* **blp** is cleaner than pdblp but still sits in the classic Python/pandas wrapper category (`python>=3.6`, mandatory pandas). xbbg moves transport and output handling into native Rust execution, reusable worker pools, Arrow output, enterprise transports, and broad `blpapi` workflow coverage.
* **polars-bloomberg** is useful when Polars is the chosen dataframe layer and has partial BQL/search-style coverage. xbbg keeps Polars as one backend while also supporting pandas, PyArrow, DuckDB, Narwhals, BDP/BDS/BDH/BDIB/BDTICK/streaming workflows, enterprise transports, middleware, diagnostics, generic service requests, and Node.js.
## Quick example
```python
import xbbg
xbbg.configure(host='localhost', port=8194)
prices = xbbg.bdp(
['AAPL US Equity', 'MSFT US Equity'],
['PX_LAST', 'VOLUME'],
)
```
Prefer the top-level helpers in these docs (`xbbg.bdp(...)`, `xbbg.configure(...)`). If you are coming from the repository README, the module-style import remains supported too: `from xbbg import blp` and `blp.bdp(...)`.
## Next steps
---
---
url: 'https://xbbg.org/python/api/surface.md'
description: Public xbbg Python package surface from the actual package exports
---
## Core request helpers
| Family | Sync | Async | Notes |
|--------|------|-------|-------|
| Generic requests | `request` | `arequest` | Direct service/operation access using typed request params |
| Reference data | `bdp`, `bds` | `abdp`, `abds` | Point-in-time and bulk-data helpers |
| Historical / intraday | `bdh`, `bdib`, `bdtick` | `abdh`, `abdib`, `abdtick` | Historical bars, intraday bars, and ticks |
| Query / search | `bql`, `bsrch`, `beqs`, `blkp`, `bport` | `abql`, `absrch`, `abeqs`, `ablkp`, `abport` | BQL, Bloomberg search/screening, instrument lookup, portfolio data |
| Field metadata | `bflds`, `bfld`, `fieldInfo`, `fieldSearch` | `abflds`, `abfld`, `afieldInfo`, `afieldSearch` | Field info and field search |
| Curves / governments / quotes | `bcurves`, `bgovts`, `bqr` | `abcurves`, `abgovts`, `abqr` | Yield curves, government securities, dealer quote request |
## Streaming and realtime helpers
| Service | Sync | Async | Use when |
|---------|------|-------|----------|
| Market data subscriptions | `subscribe`, `stream` | `asubscribe`, `astream` | Realtime Bloomberg market data |
| VWAP | `vwap` | `avwap` | `//blp/mktvwap` workflows |
| Market bars | `mktbar` | `amktbar` | `//blp/mktbar` workflows |
| Market depth | `depth` | `adepth` | B-PIPE depth data |
| Chains | `chains` | `achains` | Option/futures chain subscriptions |
`Tick` and `Subscription` are part of the public surface for streaming consumers that need explicit lifecycle and diagnostics access.
## Configuration, lifecycle, and middleware
## Backends and output format utilities
The package exports `Backend` plus utility functions for checking installed backends and supported format combinations:
The service definitions module exports `Service`, `Operation`, `OutputMode`, `RequestParams`, and `ExtractorHint`; output shapes are controlled with `Format`.
## Field cache and schema APIs
## Extension modules
| Module | Sync functions | Async functions |
|--------|----------------|-----------------|
| Historical | `dividend`, `earnings`, `turnover`, `etf_holdings` | `adividend`, `aearnings`, `aturnover`, `aetf_holdings` |
| Futures / CDX resolution | `fut_ticker`, `active_futures`, `cdx_ticker`, `active_cdx` | `afut_ticker`, `aactive_futures`, `acdx_ticker`, `aactive_cdx` |
| Currency | `convert_ccy` | `aconvert_ccy` |
| Fixed income | `yas`, `preferreds`, `corporate_bonds`, `bqr` | `ayas`, `apreferreds`, `acorporate_bonds`, `abqr` |
| Bond analytics | `bond_info`, `bond_risk`, `bond_spreads`, `bond_cashflows`, `bond_key_rates`, `bond_curve` | `abond_info`, `abond_risk`, `abond_spreads`, `abond_cashflows`, `abond_key_rates`, `abond_curve` |
| Options analytics | `option_info`, `option_greeks`, `option_pricing`, `option_chain`, `option_chain_bql`, `option_screen` | `aoption_info`, `aoption_greeks`, `aoption_pricing`, `aoption_chain`, `aoption_chain_bql`, `aoption_screen` |
| CDX analytics | `cdx_info`, `cdx_defaults`, `cdx_pricing`, `cdx_risk`, `cdx_basis`, `cdx_default_prob`, `cdx_cashflows`, `cdx_curve` | `acdx_info`, `acdx_defaults`, `acdx_pricing`, `acdx_risk`, `acdx_basis`, `acdx_default_prob`, `acdx_cashflows`, `acdx_curve` |
Extension enums include `YieldType`, `PutCall`, `ChainPeriodicity`, `StrikeRef`, `ExerciseType`, and `ExpiryMatch`.
## Markets utilities
The `xbbg.markets` module exports exchange and session helpers:
## Errors
`BlpError`, `BlpSessionError`, `BlpRequestError`, `BlpSecurityError`, `BlpFieldError`, `BlpValidationError`, `BlpTimeoutError`, `BlpInternalError`, and `BlpBPipeError` are stable public imports. See [Exceptions](/python/api/exceptions/) for details.
---
---
url: 'https://xbbg.org/python/quickstart.md'
description: Make your first Bloomberg request with xbbg
---
::: warning
You need an active Bloomberg Terminal, B-PIPE, or appropriately licensed Bloomberg connectivity to run these examples.
:::
If your environment uses Bloomberg ZFP over leased lines instead of a local Terminal or direct B-PIPE host, configure `zfp_remote` with TLS credentials before the first request. See [ZFP over Leased Lines](/python/reference/configuration/#zfp-over-leased-lines).
## 1. Configure the session
```python
import xbbg
xbbg.configure(host='localhost', port=8194)
```
Use configuration for connection facts such as host lists, auth, TLS, ZFP, SOCKS5, failover, and SDK logging. Keep individual request calls focused on the data they need.
## 2. Reference data with `bdp`
```python
# Single ticker, single field
last = xbbg.bdp('AAPL US Equity', 'PX_LAST')
# Multiple tickers and fields
snapshot = xbbg.bdp(
['AAPL US Equity', 'MSFT US Equity'],
['PX_LAST', 'VOLUME', 'NAME'],
)
```
**Example output:**
| ticker | field | value |
|--------|-------|-------|
| AAPL US Equity | PX\_LAST | 185.50 |
| AAPL US Equity | VOLUME | 45234521 |
| MSFT US Equity | PX\_LAST | 378.91 |
## 3. Historical data with `bdh`
```python
from datetime import date
history = xbbg.bdh(
'AAPL US Equity',
['PX_LAST', 'VOLUME'],
start_date=date(2024, 1, 1),
end_date=date(2024, 1, 31),
)
```
Dates accept ISO 8601 strings, `YYYYMMDD` strings, `"today"`, `datetime.date`, `datetime.datetime`, or `pandas.Timestamp`. See the [Dates and Datetimes guide](/python/guides/dates) for accepted values, override normalization, and timezone semantics.
Use Bloomberg Excel-style aliases when you want shorter historical request options:
```python
weekly = xbbg.bdh(
'AAPL US Equity',
'PX_LAST',
start_date='2024-01-01',
end_date='2024-03-31',
Per='W', # periodicitySelection='WEEKLY'
Fill='P', # nonTradingDayFillMethod='PREVIOUS_VALUE'
Points=12, # maxDataPoints=12
Dts='Show', # keep date output
DtFmt='Both', # include period labels next to dates
Sort='Reverse', # newest rows first
Direction='V', # vertical/long output shape
)
```
## 4. Bulk data with `bds`
```python
# Dividend history
dividends = xbbg.bds('AAPL US Equity', 'DVD_Hist_All')
# Index members
members = xbbg.bds('SPX Index', 'INDX_MEMBERS')
```
`bds()` and `abds()` preserve Bloomberg bulk subfield labels exactly as emitted. The only xbbg-added columns are `ticker` and `field`; field-specific columns may contain spaces, punctuation, and Bloomberg casing such as `Future's Ticker` or `Last Trade Date`. Normalize or rename these columns in application code when you need a stable schema.
## 5. Choose an output backend
```python
# Global setting
xbbg.set_backend('polars')
polars_df = xbbg.bdp('AAPL US Equity', 'PX_LAST')
# Per-call override
pandas_df = xbbg.bdp('AAPL US Equity', 'PX_LAST', backend='pandas')
# Available backends: pandas, polars, pyarrow, duckdb, narwhals
```
See [DataFrame Backends](/python/guides/backends/) and [Output Formats](/python/guides/output-formats/) for the full output model.
## 6. Run concurrent requests
```python
import asyncio
import xbbg
async def main():
apple, microsoft, alphabet = await asyncio.gather(
xbbg.abdp('AAPL US Equity', 'PX_LAST'),
xbbg.abdp('MSFT US Equity', 'PX_LAST'),
xbbg.abdp('GOOGL US Equity', 'PX_LAST'),
)
return apple, microsoft, alphabet
results = asyncio.run(main())
```
The `a`-prefixed helpers use the same API shape as the blocking helpers while letting licensed Bloomberg data requests overlap without blocking application code.
## 7. Try a fixed-income workflow
```python
from xbbg import blp
# Discover USD government curves
curves = blp.bcurves(currency='USD', curve_type='GOVERNMENT')
# Dealer quote request with bond-specific fields
quotes = blp.bqr(
'US037833FB15@MSG1 Corp',
date_offset='-2d',
include_broker_codes=True,
include_spread_price=True,
include_yield=True,
)
```
See [Fixed Income](/python/guides/fixed-income/) for curves, government securities, BQR, YAS, corporate bonds, and bond analytics.
## 8. Add production middleware
```python
from xbbg import blp
@blp.add_middleware
async def tag_request(context, call_next):
context.metadata['source'] = 'research-notebook'
return await call_next(context)
```
Middleware is the supported place for tracing, metrics, audit tags, authorization checks, policy enforcement, and standardized request metadata.
## Next steps
---
---
url: 'https://xbbg.org/javascript/api/core/interfaces/recipebackendoptions.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:287`)
## Properties
### backend?
> `optional` **backend?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:288`)
---
---
url: 'https://xbbg.org/javascript/api/core/interfaces/requestinput.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:84`)
## Properties
### elements?
> `optional` **elements?**: [`StringPair`](/javascript/api/core/interfaces/stringpair/)\[]
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:94`)
***
### endDate?
> `optional` **endDate?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:98`)
***
### endDatetime?
> `optional` **endDatetime?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:100`)
***
### eventType?
> `optional` **eventType?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:103`)
***
### eventTypes?
> `optional` **eventTypes?**: `string`\[]
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:104`)
***
### extractor?
> `optional` **extractor?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:89`)
***
### fieldIds?
> `optional` **fieldIds?**: `string`\[]
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:111`)
***
### fields?
> `optional` **fields?**: `string`\[]
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:92`)
***
### fieldTypes?
> `optional` **fieldTypes?**: [`StringPair`](/javascript/api/core/interfaces/stringpair/)\[]
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:107`)
***
### format?
> `optional` **format?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:112`)
***
### includeSecurityErrors?
> `optional` **includeSecurityErrors?**: `boolean`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:108`)
***
### interval?
> `optional` **interval?**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:105`)
***
### jsonElements?
> `optional` **jsonElements?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:96`)
***
### kwargs?
> `optional` **kwargs?**: [`StringPair`](/javascript/api/core/interfaces/stringpair/)\[]
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:95`)
***
### operation
> **operation**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:86`)
***
### options?
> `optional` **options?**: [`StringPair`](/javascript/api/core/interfaces/stringpair/)\[]
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:106`)
***
### outputTz?
> `optional` **outputTz?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:102`)
***
### overrides?
> `optional` **overrides?**: [`StringPair`](/javascript/api/core/interfaces/stringpair/)\[]
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:93`)
***
### requestId?
> `optional` **requestId?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:88`)
***
### requestOperation?
> `optional` **requestOperation?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:87`)
***
### requestTz?
> `optional` **requestTz?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:101`)
***
### searchSpec?
> `optional` **searchSpec?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:110`)
***
### securities?
> `optional` **securities?**: `string`\[]
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:90`)
***
### security?
> `optional` **security?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:91`)
***
### service
> **service**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:85`)
***
### startDate?
> `optional` **startDate?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:97`)
***
### startDatetime?
> `optional` **startDatetime?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:99`)
***
### validateFields?
> `optional` **validateFields?**: `boolean`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:109`)
---
---
url: 'https://xbbg.org/javascript/api/core/interfaces/requestoptions.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:290`)
## Properties
### backend?
> `optional` **backend?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:294`)
***
### format?
> `optional` **format?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:293`)
***
### kwargs?
> `optional` **kwargs?**: `Record`<`string`, `string` | `number` | `boolean`>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:292`)
***
### overrides?
> `optional` **overrides?**: `Record`<`string`, `string` | `number` | `boolean`>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:291`)
---
---
url: 'https://xbbg.org/javascript/api/core/interfaces/retrypolicy.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:31`)
## Properties
### backoffFactor?
> `optional` **backoffFactor?**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:34`)
***
### initialDelayMs?
> `optional` **initialDelayMs?**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:33`)
***
### maxDelayMs?
> `optional` **maxDelayMs?**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:35`)
***
### maxRetries?
> `optional` **maxRetries?**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:32`)
---
---
url: 'https://xbbg.org/python/api/schema.md'
description: Bloomberg schema introspection and stub generation
---
# xbbg.schema
Bloomberg schema introspection and stub generation.
This module provides access to cached Bloomberg service schemas
and can generate Python type stubs for IDE autocomplete support.
**Example**:
> > > import xbbg
> > > from xbbg.schema import get\_schema, list\_operations
> > >
> > > # Get schema for a service
> > >
> > > schema = await get\_schema("//blp/refdata")
> > >
> > > # List available operations
> > >
> > > ops = await list\_operations("//blp/refdata")
> > > print(ops) # \['ReferenceDataRequest', 'HistoricalDataRequest', ...]
> > >
> > > # Get enum values for an element
> > >
> > > values = await get\_enum\_values("//blp/refdata", "ReferenceDataRequest", "periodicitySelection")
## ElementInfo Objects
```python
@dataclass
class ElementInfo()
```
Schema element information.
#### from\_dict
```python
@classmethod
def from_dict(cls, d: dict[str, Any]) -> ElementInfo
```
Create from dictionary (parsed JSON).
## OperationSchema Objects
```python
@dataclass
class OperationSchema()
```
Schema for a service operation.
#### from\_dict
```python
@classmethod
def from_dict(cls, d: dict[str, Any]) -> OperationSchema
```
Create from dictionary (parsed JSON).
## ServiceSchema Objects
```python
@dataclass
class ServiceSchema()
```
Schema for a Bloomberg service.
#### from\_dict
```python
@classmethod
def from_dict(cls, d: dict[str, Any]) -> ServiceSchema
```
Create from dictionary (parsed JSON).
#### from\_json
```python
@classmethod
def from_json(cls, json_str: str) -> ServiceSchema
```
Create from JSON string.
#### get\_operation
```python
def get_operation(name: str) -> OperationSchema | None
```
Get an operation by name.
#### aget\_schema
```python
async def aget_schema(service: str) -> ServiceSchema
```
Get schema for a service (async).
Loads from cache if available, otherwise introspects the service.
**Arguments**:
* `service` - Service URI (e.g., "//blp/refdata")
**Returns**:
ServiceSchema object with operations and element definitions.
#### aget\_operation
```python
async def aget_operation(service: str, operation: str) -> OperationSchema
```
Get schema for a specific operation (async).
**Arguments**:
* `service` - Service URI (e.g., "//blp/refdata")
* `operation` - Operation name (e.g., "ReferenceDataRequest")
**Returns**:
OperationSchema object with request/response definitions.
#### alist\_operations
```python
async def alist_operations(service: str) -> list[str]
```
List all operations for a service (async).
**Arguments**:
* `service` - Service URI (e.g., "//blp/refdata")
**Returns**:
List of operation names.
#### aget\_enum\_values
```python
async def aget_enum_values(service: str, operation: str,
element: str) -> list[str] | None
```
Get valid enum values for an element (async).
**Arguments**:
* `service` - Service URI
* `operation` - Operation name
* `element` - Element name
**Returns**:
List of valid enum values, or None if not an enum.
#### alist\_valid\_elements
```python
async def alist_valid_elements(service: str,
operation: str) -> list[str] | None
```
List all valid element names for an operation (async).
**Arguments**:
* `service` - Service URI
* `operation` - Operation name
**Returns**:
List of valid element names.
#### get\_schema
```python
def get_schema(service: str) -> ServiceSchema
```
Get schema for a service (sync wrapper).
#### get\_operation
```python
def get_operation(service: str, operation: str) -> OperationSchema
```
Get schema for a specific operation (sync wrapper).
#### list\_operations
```python
def list_operations(service: str) -> list[str]
```
List all operations for a service (sync wrapper).
#### get\_enum\_values
```python
def get_enum_values(service: str, operation: str,
element: str) -> list[str] | None
```
Get valid enum values for an element (sync wrapper).
#### list\_valid\_elements
```python
def list_valid_elements(service: str, operation: str) -> list[str] | None
```
List all valid element names for an operation (sync wrapper).
#### list\_cached\_schemas
```python
def list_cached_schemas() -> list[str]
```
List all cached service URIs.
#### invalidate\_schema
```python
def invalidate_schema(service: str) -> None
```
Invalidate a cached schema.
#### clear\_schema\_cache
```python
def clear_schema_cache() -> None
```
Clear all cached schemas.
#### configure\_ide\_stubs
```python
def configure_ide_stubs(stubs_dir: Path | str | None = None,
ide: str | None = None) -> str
```
Configure IDE to recognize xbbg type stubs.
Only modifies existing config files - does not create new ones.
**Arguments**:
* `stubs_dir` - Stubs directory (default: ~/.xbbg/stubs/)
* `ide` - IDE to configure: "vscode", "pyright", "pyproject", "ty", or None for auto-detect
**Returns**:
Message describing what was configured or manual instructions.
#### generate\_stubs
```python
def generate_stubs(service: str, output_dir: Path | str | None = None) -> str
```
Generate Python type stubs for a service.
Creates .pyi files with TypedDict definitions for request/response types.
Stubs are generated locally for IDE support - never committed to repos.
**Arguments**:
* `service` - Service URI (e.g., "//blp/refdata")
* `output_dir` - Output directory (default: ~/.xbbg/stubs/)
**Returns**:
Path to the generated stub file.
---
---
url: 'https://xbbg.org/javascript/api/core/interfaces/serveraddress.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:10`)
## Properties
### host
> **host**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:11`)
***
### port
> **port**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:12`)
---
---
url: 'https://xbbg.org/python/api/services.md'
description: 'Bloomberg service definitions, operations, and enums'
---
# xbbg.services
Bloomberg service definitions and request parameters.
Enum definitions (Service, Operation, ExtractorHint, Format, OutputMode) are
generated from `defs/bloomberg.toml` into `_services_gen.py`. This module
re-exports them and provides the hand-written :class:`RequestParams` dataclass.
Example::
from xbbg import Service, Operation, RequestParams
params = RequestParams(
service=Service.REFDATA,
operation=Operation.REFERENCE\_DATA,
securities=\["AAPL US Equity"],
fields=\["PX\_LAST"],
)
## RequestParams Objects
```python
@dataclass
class RequestParams()
```
Validated request parameters for the Bloomberg API.
This dataclass holds all possible parameters for Bloomberg requests.
Not all parameters are used for all request types - the Python layer
validates that required parameters are present for each operation.
The Rust layer handles default extractor resolution via
`RequestParams::with_defaults()`, so Python only passes an explicit
extractor when the caller overrides it.
**Attributes**:
* `service` - Bloomberg service URI (e.g., `"//blp/refdata"`).
* `operation` - Request operation name (e.g., `"ReferenceDataRequest"`).
* `request_operation` - Actual Bloomberg operation name when using
`Operation.RAW_REQUEST` as the low-level escape hatch.
* `securities` - List of security identifiers (for multi-security requests).
* `security` - Single security identifier (for intraday requests).
* `fields` - List of field names to retrieve.
* `overrides` - List of (field, value) tuples for field overrides.
* `elements` - List of (name, value) tuples for generic request elements (BQL, bsrch).
* `start_date` - Start date for historical requests (YYYYMMDD format).
* `end_date` - End date for historical requests (YYYYMMDD format).
* `start_datetime` - Start datetime for intraday requests (ISO format).
* `end_datetime` - End datetime for intraday requests (ISO format).
* `request_tz` - How naive intraday datetimes are interpreted before the API call
(`UTC`, `local`, `exchange`, `NY`/`LN`/�, reference ticker, or IANA).
* `output_tz` - Relabel Arrow `time` to this zone (same instants; handled in Rust).
* `event_type` - Event type for intraday bars (TRADE, BID, ASK, etc.).
* `event_types` - Event types for intraday ticks (TRADE, BID, ASK, etc.).
* `interval` - Bar interval in minutes for intraday bars.
* `options` - Additional Bloomberg options as (key, value) tuples.
* `field_types` - Manual type overrides for fields (for issue `168`).
* `output` - Output format (arrow or json).
* `extractor` - Override the auto-detected extractor hint. When `None`
the Rust layer picks the correct extractor for the operation.
* `format` - Output format (LONG, LONG\_TYPED, LONG\_WITH\_METADATA).
* `include_security_errors` - When True for ReferenceData requests, include
`__SECURITY_ERROR__` rows for securities that failed.
* `validate_fields` - Optional per-request override for field validation.
`True` forces strict validation, `False` disables it, and
`None` (default) follows engine configuration.
#### \_\_post\_init\_\_
```python
def __post_init__() -> None
```
Convert enums to strings and set defaults.
#### validate
```python
def validate() -> None
```
Validate parameters for the given operation.
**Raises**:
* `BlpValidationError` - If required parameters are missing or invalid.
#### to\_dict
```python
def to_dict() -> dict[str, object]
```
Convert to dictionary for passing to Rust.
Only non-`None` values are included. When *extractor* is `None`
the key is omitted so the Rust layer can apply its own default via
`RequestParams::with_defaults()`.
**Returns**:
Dictionary suitable for Rust consumption.
---
---
url: 'https://xbbg.org/javascript/api/core/interfaces/sessionwindowsinfo.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:560`)
## Properties
### allday?
> `optional` **allday?**: [`TimeRange`](/javascript/api/core/interfaces/timerange/)
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:562`)
***
### am?
> `optional` **am?**: [`TimeRange`](/javascript/api/core/interfaces/timerange/)
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:565`)
***
### day?
> `optional` **day?**: [`TimeRange`](/javascript/api/core/interfaces/timerange/)
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:561`)
***
### pm?
> `optional` **pm?**: [`TimeRange`](/javascript/api/core/interfaces/timerange/)
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:566`)
***
### post?
> `optional` **post?**: [`TimeRange`](/javascript/api/core/interfaces/timerange/)
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:564`)
***
### pre?
> `optional` **pre?**: [`TimeRange`](/javascript/api/core/interfaces/timerange/)
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:563`)
---
---
url: 'https://xbbg.org/javascript/api/core/functions/setloglevel.md'
---
> **setLogLevel**(`level`): `void`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:791`)
## Parameters
### level
`string`
## Returns
`void`
---
---
url: 'https://xbbg.org/javascript/api/core/interfaces/socks5config.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:38`)
## Properties
### host
> **host**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:39`)
***
### port
> **port**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:40`)
---
---
url: 'https://xbbg.org/python/guides/streaming.md'
description: Real-time market data subscriptions
---
xbbg provides two interfaces for real-time Bloomberg data: `stream()` / `astream()` for simple iteration, and `subscribe()` / `asubscribe()` for full lifecycle control. All four accept the same parameters; the `a`-prefixed variants are the canonical async implementations — the sync variants run them in a background thread.
## Choosing an Interface
| Use case | Function |
|----------|----------|
| Simple iteration, no dynamic changes | `stream()` (sync) or `astream()` (async) |
| Dynamic add/remove, health inspection | `subscribe()` (sync) or `asubscribe()` (async) |
| Running inside an existing async event loop | `astream()` or `asubscribe()` |
| Script with no event loop | `stream()` or `subscribe()` |
Every subscription is **isolated** — each `subscribe()` / `asubscribe()` call gets its own Bloomberg session from the pool, so topic streams cannot cross-contaminate one another.
***
## Basic Streaming
`stream()` and `astream()` are context-manager generators. Break out of the loop to stop the subscription cleanly.
::: details Async
```python
from xbbg import blp
async def main():
async for batch in blp.astream(['AAPL US Equity', 'MSFT US Equity'], ['LAST_PRICE', 'BID', 'ASK']):
# batch is a narwhals DataFrame (or pyarrow.RecordBatch if raw=True)
print(batch)
```
:::
::: details Sync
```python
from xbbg import blp
for batch in blp.stream(['AAPL US Equity', 'MSFT US Equity'], ['LAST_PRICE', 'BID', 'ASK']):
print(batch)
```
:::
Each `batch` is a narwhals DataFrame by default, containing one or more ticks that arrived together. Use `raw=True` to receive raw `pyarrow.RecordBatch` objects for maximum throughput.
```python
async for batch in blp.astream(['AAPL US Equity'], ['LAST_PRICE'], raw=True):
# batch: pyarrow.RecordBatch
df = batch.to_pandas()
```
::: info
`stream()` runs the async implementation in a background thread. Use `astream()` inside an existing event loop (FastAPI, Jupyter, etc.) to avoid thread overhead.
:::
---
## Full Subscription Lifecycle
`asubscribe()` returns a `Subscription` handle that you iterate separately. This gives you dynamic add/remove and access to health metadata.
### Create and iterate
```python
from xbbg import blp
async def main():
sub = await blp.asubscribe(
['AAPL US Equity', 'MSFT US Equity'],
['LAST_PRICE', 'BID', 'ASK'],
)
async for batch in sub:
print(batch)
```
### Context manager
Use `async with` to guarantee cleanup on exit or exception:
```python
async with await blp.asubscribe(['AAPL US Equity'], ['LAST_PRICE']) as sub:
count = 0
async for batch in sub:
print(batch)
count += 1
if count >= 100:
break
```
### Add tickers dynamically
Tickers can be added while the subscription is active. The new topics are subscribed on the same Bloomberg session:
```python
sub = await blp.asubscribe(['AAPL US Equity'], ['LAST_PRICE', 'BID', 'ASK'])
async for batch in sub:
print(batch)
if should_add_more:
await sub.add(['MSFT US Equity', 'GOOG US Equity'])
should_add_more = False
```
### Remove tickers
```python
await sub.remove(['AAPL US Equity'])
```
Removed tickers stop delivering updates immediately. The remaining tickers continue unaffected.
### Unsubscribe
```python
# Clean close — discard buffered data
await sub.unsubscribe()
# Drain — return any remaining buffered batches before closing
remaining = await sub.unsubscribe(drain=True)
```
### Subscription properties
| Property | Type | Description |
|----------|------|-------------|
| `sub.tickers` | `list[str]` | Currently subscribed tickers |
| `sub.fields` | `list[str]` | Subscribed fields |
| `sub.is_active` | `bool` | Whether the subscription is open |
| `sub.all_failed` | `bool` | True if every ticker has failed or terminated |
***
## Subscription Configuration
Per-subscription tuning is done via keyword arguments on `asubscribe()` and `astream()`.
### `all_fields`
By default, Bloomberg delivers only the fields you requested. Setting `all_fields=True` exposes all top-level scalar fields Bloomberg sends (including INITPAINT summary fields for the initial snapshot):
```python
# Receive INITPAINT fields and any extra scalar fields Bloomberg sends
sub = await blp.asubscribe(
['XBTUSD Curncy'],
['LAST_PRICE', 'BID', 'ASK'],
all_fields=True,
)
```
### `flush_threshold`, `stream_capacity`, `overflow_policy`
These control the backpressure pipeline between the Bloomberg SDK event thread and your Python consumer.
```python
from xbbg import blp, configure
# Global defaults (applied to all new subscriptions)
configure(
subscription_flush_threshold=10, # buffer up to 10 ticks before flushing
subscription_stream_capacity=512, # internal channel depth
overflow_policy='drop_newest', # what to do when the channel is full
)
```
You can also pass them per-subscription to `asubscribe()` and `astream()`:
```python
sub = await blp.asubscribe(
['AAPL US Equity'],
['LAST_PRICE', 'BID', 'ASK'],
flush_threshold=5,
stream_capacity=1024,
overflow_policy='block', # block the Rust thread until Python catches up
)
```
| Parameter | Default | Description |
|-----------|---------|-------------|
| `flush_threshold` | `1` | Ticks buffered before flushing to Python. Increase for throughput, decrease for latency. |
| `stream_capacity` | `256` | Backpressure buffer size (number of batches). |
| `overflow_policy` | `'drop_newest'` | Slow-consumer policy: `'drop_newest'` or `'block'`. |
::: warning
`overflow_policy='block'` prevents data loss but will stall the Bloomberg SDK event thread if your consumer is too slow. Use it only when every tick is critical and your processing loop is fast enough to keep up.
:::
---
## Specialized Streams
xbbg provides dedicated functions for Bloomberg's specialized subscription services. All return a `Subscription` handle and follow the same async iteration pattern. Sync wrappers (`vwap`, `mktbar`, `depth`, `chains`) are also available.
### VWAP — `avwap()` / `vwap()`
Streaming Volume Weighted Average Price via `//blp/mktvwap`.
```python
# Basic — default fields: RT_PX_VWAP, RT_VWAP_VOLUME
sub = await blp.avwap(['AAPL US Equity'])
async for batch in sub:
print(batch)
await sub.unsubscribe()
```
```python
# Custom time window
sub = await blp.avwap(
['AAPL US Equity', 'MSFT US Equity'],
start_time='09:30',
end_time='16:00',
)
```
```python
# Request additional VWAP fields
sub = await blp.avwap(
'AAPL US Equity',
['RT_PX_VWAP', 'RT_VWAP_VOLUME', 'RT_VWAP_TURNOVER'],
)
```
| Parameter | Default | Description |
|-----------|---------|-------------|
| `tickers` | required | One or more securities |
| `fields` | `['RT_PX_VWAP', 'RT_VWAP_VOLUME']` | Fields to subscribe to |
| `start_time` | `None` | VWAP calculation start (e.g., `'09:30'`) |
| `end_time` | `None` | VWAP calculation end (e.g., `'16:00'`) |
### Market Bars — `amktbar()` / `mktbar()`
Streaming real-time OHLCV bars via `//blp/mktbar`. Like `bdib()` but live as bars form.
Default fields: `OPEN`, `HIGH`, `LOW`, `CLOSE`, `VOLUME`, `NUM_TRADES`.
```python
# 1-minute bars (default interval)
sub = await blp.amktbar('AAPL US Equity')
async for batch in sub:
print(batch)
```
```python
# 5-minute bars with a session window
async with await blp.amktbar(
['AAPL US Equity', 'MSFT US Equity'],
interval=5,
start_time='09:30',
end_time='16:00',
) as sub:
async for batch in sub:
print(batch)
```
| Parameter | Default | Description |
|-----------|---------|-------------|
| `tickers` | required | One or more securities |
| `interval` | `1` | Bar interval in minutes |
| `start_time` | `None` | Session start in `HH:MM` format |
| `end_time` | `None` | Session end in `HH:MM` format |
### Market Depth — `adepth()` / `depth()`
::: warning
Requires a Bloomberg **B-PIPE license**. Not available with standard Terminal connections. Raises `BlpBPipeError` if the service is unavailable.
:::
Streaming Level 2 order book data via `//blp/mktdepth`. Fields are implicit (provided by Bloomberg).
```python
from xbbg.exceptions import BlpBPipeError
from xbbg import blp
try:
async with await blp.adepth('AAPL US Equity') as sub:
async for batch in sub:
print(batch) # Bid/ask levels and sizes
except BlpBPipeError as e:
print(f"B-PIPE required: {e}")
```
### Option and Futures Chains — `achains()` / `chains()`
::: warning
Requires a Bloomberg **B-PIPE license**. Not available with standard Terminal connections. Raises `BlpBPipeError` if the service is unavailable.
:::
Streaming option or futures chain updates via `//blp/mktlist`.
```python
# Option chain (default)
async with await blp.achains('AAPL US Equity') as sub:
async for batch in sub:
print(batch)
```
```python
# Futures chain
sub = await blp.achains('ES1 Index', chain_type='FUTURES')
async for batch in sub:
print(batch)
await sub.unsubscribe()
```
| Parameter | Default | Description |
|-----------|---------|-------------|
| `underlying` | required | Underlying security identifier |
| `chain_type` | `'OPTIONS'` | `'OPTIONS'` or `'FUTURES'` |
***
## Health and Observability
The `Subscription` object exposes several properties for runtime inspection. None of these require pausing iteration — they are safe to read at any point.
### `status`
A combined snapshot of the subscription's operational state:
```python
print(sub.status)
# {
# 'active': True,
# 'all_failed': False,
# 'tickers': ['AAPL US Equity', 'MSFT US Equity'],
# 'failed_tickers': [],
# 'topic_states': {
# 'AAPL US Equity': {'state': 'SUBSCRIBED', 'last_change_us': 1711000000000},
# 'MSFT US Equity': {'state': 'SUBSCRIBED', 'last_change_us': 1711000000001},
# },
# 'session': {...},
# 'admin': {...},
# 'services': {...},
# }
```
### `topic_states`
Per-ticker lifecycle state keyed by ticker string. Useful for confirming that tickers are in `SUBSCRIBED` state before processing data:
```python
for ticker, state_info in sub.topic_states.items():
print(f"{ticker}: {state_info['state']}")
```
### `failed_tickers`
List of tickers Bloomberg rejected or terminated. In a mixed-subscription scenario (some tickers valid, some invalid), this will be non-empty while `is_active` remains `True` as long as at least one ticker is healthy:
```python
if sub.failed_tickers:
print("Failed:", sub.failed_tickers)
```
### `failures`
Detailed failure records, each containing `ticker`, `reason`, and `kind` (`"failure"` or `"terminated"`):
```python
for f in sub.failures:
print(f"{f['ticker']}: {f['reason']} ({f['kind']})")
```
### `events`
Bounded lifecycle event history for the subscription. Each entry contains `at_us` (microsecond timestamp), `category`, `level`, `message_type`, `topic`, and `detail`:
```python
for event in sub.events:
print(f"[{event['level']}] {event['message_type']}: {event['detail']}")
```
### `stats`
Subscription throughput metrics:
```python
print(sub.stats)
# {
# 'messages_received': 4821,
# 'dropped_batches': 0,
# 'batches_sent': 4821,
# 'slow_consumer': False,
# 'data_loss_events': 0,
# 'last_message_us': 1711000123456,
# 'effective_overflow_policy': 'drop_newest',
# }
```
| Key | Description |
|-----|-------------|
| `messages_received` | Total messages received from Bloomberg |
| `dropped_batches` | Batches dropped due to overflow |
| `batches_sent` | Batches successfully delivered to Python |
| `slow_consumer` | `True` if Bloomberg signalled `DATALOSS` |
| `data_loss_events` | Total Bloomberg data-loss signals observed |
| `effective_overflow_policy` | Runtime policy used by the Rust stream |
***
## Error Handling
### Topic failure isolation
Bloomberg's subscription model isolates failures at the topic level. If one ticker is invalid or gets terminated, the other tickers in the same subscription continue delivering data. Your loop keeps running; only `failed_tickers` grows.
```python
sub = await blp.asubscribe(
['AAPL US Equity', 'INVALID_TICKER'],
['LAST_PRICE'],
)
async for batch in sub:
# AAPL ticks still arrive; INVALID_TICKER never produces data
print(batch)
print("Failed so far:", sub.failed_tickers)
```
### Stopping when all tickers fail
Use `all_failed` to detect the total-failure case and exit cleanly:
```python
sub = await blp.asubscribe(['AAPL US Equity', 'MSFT US Equity'], ['LAST_PRICE'])
async for batch in sub:
process(batch)
if sub.all_failed:
print("All tickers failed:", sub.failed_tickers)
break
await sub.unsubscribe()
```
### Handling partial failures at startup
Check `topic_states` after a short wait to confirm which tickers successfully subscribed before committing downstream resources:
```python
import asyncio
sub = await blp.asubscribe(
['AAPL US Equity', 'INVALID_TICKER', 'MSFT US Equity'],
['LAST_PRICE', 'BID', 'ASK'],
)
# Brief wait for Bloomberg's INITPAINT / subscription status events
await asyncio.sleep(2)
active = [t for t, s in sub.topic_states.items() if s['state'] == 'SUBSCRIBED']
failed = sub.failed_tickers
print(f"Active: {active}")
print(f"Failed: {failed}")
if not active:
await sub.unsubscribe()
raise RuntimeError("No tickers subscribed successfully")
async for batch in sub:
process(batch)
```
### Connection interruption
Each subscription session is isolated. If the session drops and reconnects, Bloomberg will resend INITPAINT (initial snapshot) events. The `events` property records session lifecycle transitions you can inspect to detect reconnect cycles.
***
## See Also
* [API Reference — `subscribe` / `asubscribe`](/python/api/blp/#asubscribe)
* [API Reference — `stream` / `astream`](/python/api/blp/#astream)
* [Engine Configuration](/python/reference/configuration/) for `subscription_pool_size`, global flush/overflow defaults
---
---
url: 'https://xbbg.org/javascript/api/core/interfaces/streamoptions.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:296`)
## Properties
### flushThreshold?
> `optional` **flushThreshold?**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:298`)
***
### options?
> `optional` **options?**: `string`\[]
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:297`)
***
### overflowPolicy?
> `optional` **overflowPolicy?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:299`)
***
### streamCapacity?
> `optional` **streamCapacity?**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:300`)
---
---
url: 'https://xbbg.org/javascript/api/core/interfaces/stringpair.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:5`)
## Properties
### key
> **key**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:6`)
***
### value
> **value**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:7`)
---
---
url: 'https://xbbg.org/javascript/api/core/functions/subscribe.md'
---
> **subscribe**(`tickers`, `fields`): `Promise`<[`Subscription`](/javascript/api/core/classes/subscription/)>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:750`)
## Parameters
### tickers
`string` | `string`\[]
### fields
`string` | `string`\[]
## Returns
`Promise`<[`Subscription`](/javascript/api/core/classes/subscription/)>
---
---
url: 'https://xbbg.org/javascript/api/core/classes/subscription.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:303`)
## Implements
* `AsyncIterator`<`Table`>
## Constructors
### Constructor
> **new Subscription**(): `Subscription`
#### Returns
`Subscription`
## Properties
### fields
> `readonly` **fields**: `string`\[]
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:309`)
***
### isActive
> `readonly` **isActive**: `boolean`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:310`)
***
### stats
> `readonly` **stats**: [`SubscriptionStats`](/javascript/api/core/interfaces/subscriptionstats/)
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:311`)
***
### tickers
> `readonly` **tickers**: `string`\[]
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:308`)
## Methods
### \[asyncIterator]\()
> **\[asyncIterator]**(): `AsyncIterator`<`Table`<`any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:312`)
#### Returns
`AsyncIterator`<`Table`<`any`>>
***
### add()
> **add**(`tickers`): `Promise`<`void`>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:305`)
#### Parameters
##### tickers
`string`\[]
#### Returns
`Promise`<`void`>
***
### next()
> **next**(): `Promise`<`IteratorResult`<`Table`<`any`>, `any`>>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:304`)
#### Returns
`Promise`<`IteratorResult`<`Table`<`any`>, `any`>>
#### Implementation of
`AsyncIterator.next`
***
### remove()
> **remove**(`tickers`): `Promise`<`void`>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:306`)
#### Parameters
##### tickers
`string`\[]
#### Returns
`Promise`<`void`>
***
### unsubscribe()
> **unsubscribe**(`drain?`): `Promise`<`Table`<`any`>\[]>
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:307`)
#### Parameters
##### drain?
`boolean`
#### Returns
`Promise`<`Table`<`any`>\[]>
---
---
url: 'https://xbbg.org/javascript/api/core/interfaces/subscriptionstats.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:115`)
## Properties
### batchesSent
> **batchesSent**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:118`)
***
### droppedBatches
> **droppedBatches**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:117`)
***
### messagesReceived
> **messagesReceived**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:116`)
***
### slowConsumer
> **slowConsumer**: `boolean`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:119`)
---
---
url: 'https://xbbg.org/javascript/api/core/interfaces/tickerparts.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:531`)
## Properties
### asset
> **asset**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:534`)
***
### exchange?
> `optional` **exchange?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:535`)
***
### index
> **index**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:533`)
***
### prefix
> **prefix**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:532`)
---
---
url: 'https://xbbg.org/javascript/api/core/interfaces/timerange.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:526`)
## Properties
### end
> **end**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:528`)
***
### start
> **start**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:527`)
---
---
url: 'https://xbbg.org/javascript/api/core/interfaces/tlsconfig.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:23`)
## Properties
### clientCredentials?
> `optional` **clientCredentials?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:24`)
***
### clientCredentialsPassword?
> `optional` **clientCredentialsPassword?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:25`)
***
### crlFetchTimeoutMs?
> `optional` **crlFetchTimeoutMs?**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:28`)
***
### handshakeTimeoutMs?
> `optional` **handshakeTimeoutMs?**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:27`)
***
### trustMaterial?
> `optional` **trustMaterial?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:26`)
---
---
url: 'https://xbbg.org/javascript/api/core/interfaces/turnoveroptions.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:278`)
## Properties
### backend?
> `optional` **backend?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:281`)
***
### ccy?
> `optional` **ccy?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:279`)
***
### factor?
> `optional` **factor?**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:280`)
---
---
url: 'https://xbbg.org/python/reference/type-mappings.md'
description: Bloomberg to Arrow type mappings
---
xbbg maps every Bloomberg field type to an Apache Arrow type at the Rust layer, before data surfaces in Python.
This reference covers the full mapping table, how types are resolved at runtime, and how to override them.
## BLPAPI to Arrow Type Mapping
Bloomberg's `//blp/apiflds` service exposes two type descriptors per field: `datatype` (preferred) and `ftype` (fallback).
The Rust engine reads whichever is present and maps it to an Arrow type.
| Bloomberg ftype / datatype | Arrow Type | Type string | Notes |
|---------------------------|------------|-------------|-------|
| `Double`, `Real`, `Price`, `Float` | Float64 | `float64` | All floating-point Bloomberg types map to Float64 |
| `Int32`, `Integer` | Int64 | `int64` | Promoted to Int64 for consistency |
| `Int64`, `Long` | Int64 | `int64` | |
| `String`, `LongCharacter`, `StringOrReal` | Utf8 | `string` | |
| `Character`, `Char` | Utf8 | `string` | Also used for Y/N boolean fields — see below |
| `Date` | Date32 | `date32` | Days since Unix epoch (1970-01-01) |
| `Datetime` | Timestamp (UTC, microseconds) | `timestamp` | Full datetime with date and time parts |
| `Time` | Time64 (microseconds) | `time64` | Time-of-day only; no date component |
| `DateOrTime` | Utf8 | `string` | Ambiguous; kept as string to avoid data loss |
| `Boolean`, `Bool` | Boolean | `bool` | |
| `BulkFormat`, `Bulk` | Utf8 | `string` | Bulk data encoded as JSON string |
| Unknown / unrecognised | Utf8 | `string` | Safe default |
::: info
Bloomberg's `Int32` is normalised to Arrow `Int64` by the Rust engine. There is no `Int32` column in xbbg output.
:::
## Type Resolution Hierarchy
For every field in a request, the Rust engine resolves the Arrow type using a four-step hierarchy, stopping at the first match:
1. **Manual override** — the `field_types` parameter passed to the request function (highest priority).
2. **Disk cache** — `~/.xbbg/field_cache.json` (configurable via `field_cache_path`). Loaded at engine start.
3. **API query** — live lookup against Bloomberg's `//blp/apiflds` service. Result written back to cache.
4. **Request default** — `string` for `bdp`/`bds`, `float64` for `bdh` (lowest priority, applied when no type information is available).
All caching, disk I/O, and API fallback are implemented in Rust (`crates/xbbg-async/src/field_cache.rs`).
The Python `field_cache` module is a thin wrapper that delegates every call to the engine.
Within the API query (step 3), the engine prefers the `datatype` field from the `//blp/apiflds` response.
If `datatype` is absent, it falls back to `ftype`.
## Boolean Detection
Bloomberg frequently stores boolean fields at the wire level as `Char` elements containing ASCII `Y` (byte 89) or `N` (byte 78),
even when the logical field type is Boolean.
The Rust engine calls `blpapi_Element_getValueAsBool` for every `Char`/`Byte` element —
Bloomberg's C API coerces `Y`/`N` to `true`/`false` transparently.
If that call fails, the value falls back to a raw byte.
Because of this coercion, fields whose `ftype` is `Character` but whose values are always `Y`/`N`
(such as many flag fields) will arrive in Python as Arrow `Boolean`, not `Utf8`.
The field cache stores the resolved type; inspecting it with `get_field_info` will show `bool` for such fields.
## Field Type Cache
The field type cache avoids repeated `//blp/apiflds` round-trips for fields you request frequently.
It persists to `~/.xbbg/field_cache.json` and is loaded automatically when the engine starts.
### Module-level functions
```python
from xbbg import blp
from xbbg.field_cache import (
resolve_field_types,
aresolve_field_types,
cache_field_types,
get_field_info,
clear_field_cache,
get_field_cache_stats,
)
```
| Function | Description |
|----------|-------------|
| `resolve_field_types(fields, overrides=None)` | Resolve Arrow type strings for a list of fields. Queries API for cache misses. Returns `dict[str, str]`. |
| `aresolve_field_types(fields, overrides=None)` | Async version of `resolve_field_types`. |
| `cache_field_types(fields)` | Pre-populate the cache for a list of fields without returning results. Async. |
| `get_field_info(fields)` | Return `list[FieldInfo]` with `field_id`, `arrow_type`, `description`, `category`. Async. |
| `clear_field_cache()` | Flush both the in-memory cache and the on-disk JSON file. |
| `get_field_cache_stats()` | Return `{"entry_count": int, "cache_path": str}`. |
**Pre-populating the cache** before bulk requests avoids per-request API lookups:
```python
import asyncio
from xbbg.field_cache import cache_field_types
# Run once at startup
asyncio.run(cache_field_types([
"PX_LAST", "VOLUME", "NAME", "INDUSTRY_SECTOR", "DVD_EX_DT",
]))
```
**Inspecting the cache:**
```python
from xbbg.field_cache import get_field_cache_stats, resolve_field_types
stats = get_field_cache_stats()
print(stats["entry_count"]) # e.g. 42
print(stats["cache_path"]) # e.g. /home/user/.xbbg/field_cache.json
types = resolve_field_types(["PX_LAST", "NAME", "VOLUME"])
# {'PX_LAST': 'float64', 'NAME': 'string', 'VOLUME': 'float64'}
```
**Changing the cache location** must be done before the engine starts:
```python
import xbbg
xbbg.configure(field_cache_path="/data/bloomberg/field_cache.json")
```
### FieldTypeCache class
`FieldTypeCache` is a facade over the Rust resolver, kept for compatibility:
```python
from xbbg.field_cache import FieldTypeCache
cache = FieldTypeCache()
types = cache.resolve_types(["PX_LAST", "NAME"])
print(cache.cache_path) # active JSON path
print(cache.stats) # {"entry_count": ..., "cache_path": ...}
cache.clear_cache()
```
## LONG\_TYPED Column Mapping
When `format='long_typed'` is passed, each row carries one value in the typed column that matches the field's resolved Arrow type.
All other value columns are null for that row.
| Arrow Type | Typed column | Arrow schema |
|------------|--------------|--------------|
| Float64 | `value_f64` | `Float64` |
| Int64 | `value_i64` | `Int64` |
| Utf8 | `value_str` | `Utf8` |
| Boolean | `value_bool` | `Boolean` |
| Date32 | `value_date` | `Date32` |
| Timestamp (UTC, µs) | `value_ts` | `Timestamp[us, UTC]` |
The full column order for `LONG_TYPED` output is:
`ticker`, `field`, `value_f64`, `value_i64`, `value_str`, `value_bool`, `value_date`, `value_ts`.
```python
from xbbg import blp
df = blp.bdp(
["AAPL US Equity", "MSFT US Equity"],
["PX_LAST", "VOLUME", "NAME", "DVD_EX_DT"],
format="long_typed",
)
# PX_LAST → value_f64 populated, others null
# VOLUME → value_f64 populated (float64 default for bdp)
# NAME → value_str populated
# DVD_EX_DT → value_date populated
```
::: info
`LONG_TYPED` is supported by all backends including lazy backends (Polars lazy, DuckDB, narwhals lazy).
:::
## Time Types
Bloomberg has three distinct temporal datatypes. xbbg maps each to a different Arrow type to preserve semantics:
### Date32
Fields with Bloomberg `datatype=Date` (e.g. `DVD_EX_DT`, `MATURITY`) are stored as `Date32` —
a 32-bit integer counting days since 1970-01-01.
This is lossless and compact.
### Timestamp (microseconds, UTC)
Fields with Bloomberg `datatype=Datetime` (e.g. `LAST_TRADE_TIME`, `NEWS_SENTIMENT_DT_TIME`) are stored
as `Timestamp[us, UTC]`. The Rust engine checks the Bloomberg datetime's parts bitmask to confirm both
date and time components are present before emitting a Timestamp.
### Time64 (microseconds)
Fields with Bloomberg `datatype=Time` (e.g. `TIME_OF_TRADE`, real-time time-of-day fields) are stored as
`Time64[us]` — microseconds elapsed since midnight with no date component.
Bloomberg Time fields have zeroed date parts. Converting them to a Timestamp would produce a garbage
value anchored near year 0 (or the Unix epoch) rather than a meaningful wall-clock time.
The Rust engine detects this case for `Datetime` fields too: if the date parts bitmask is zero, the value
is emitted as `Time64` even when the Bloomberg datatype is `Datetime`.
The mapping in `value_ts` (LONG\_TYPED) captures both Timestamp and Datetime values.
Pure time-of-day values (`Time64`) do not appear in `value_ts`; they appear in `value_str` unless
the field cache has resolved them as a time type and the schema is built accordingly.
## Manual Type Overrides
You can override the resolved type for any field on a per-request basis using the `field_types` parameter.
This is the highest-priority step in the resolution hierarchy and takes precedence over both the cache
and the live API lookup.
```python
from xbbg import blp
# Bloomberg resolves VOLUME as float64 by default.
# Override to int64 for cleaner output.
df = blp.bdp(
"AAPL US Equity",
["PX_LAST", "VOLUME"],
field_types={"VOLUME": "int64"},
)
```
Accepted type strings are:
| Type string(s) | Arrow type |
|----------------|------------|
| `float64`, `float`, `double`, `f64` | Float64 |
| `int64`, `int`, `integer`, `i64` | Int64 |
| `int32`, `i32` | Int32 |
| `bool`, `boolean` | Boolean |
| `date32`, `date` | Date32 |
| `timestamp`, `datetime`, `timestamp_us` | Timestamp (UTC, µs) |
| `time64`, `time`, `time64_us` | Time64 (µs) |
| `string` (or any unrecognised string) | Utf8 |
### Field validation
The `validate_fields` parameter controls whether unknown field mnemonics are rejected:
```python
# Strict: raise on any field not found in //blp/apiflds
df = blp.bdp("AAPL US Equity", ["PX_LAST", "BADFIELD"], validate_fields=True)
# Lenient (default, follows engine-level validation_mode setting)
df = blp.bdp("AAPL US Equity", ["PX_LAST", "BADFIELD"], validate_fields=None)
# Disabled: skip validation regardless of engine config
df = blp.bdp("AAPL US Equity", ["PX_LAST", "BADFIELD"], validate_fields=False)
```
The engine-level default is `validation_mode='disabled'`.
Set it globally with `xbbg.configure(validation_mode='strict')` or `'lenient'`.
---
---
url: 'https://xbbg.org/javascript/api/core/functions/version.md'
---
> **version**(): `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:790`)
## Returns
`string`
---
---
url: 'https://xbbg.org/javascript/api/core/functions/wraperror.md'
---
> **wrapError**(`napiError`): [`BlpError`](/javascript/api/core/classes/blperror/)
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:184`)
## Parameters
### napiError
`Error`
## Returns
[`BlpError`](/javascript/api/core/classes/blperror/)
---
---
url: 'https://xbbg.org/javascript/api/core/interfaces/yasoptions.md'
---
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:247`)
## Properties
### backend?
> `optional` **backend?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:254`)
***
### benchmark?
> `optional` **benchmark?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:253`)
***
### price?
> `optional` **price?**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:252`)
***
### settleDt?
> `optional` **settleDt?**: `string`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:248`)
***
### spread?
> `optional` **spread?**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:250`)
***
### yieldType?
> `optional` **yieldType?**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:249`)
***
### yieldVal?
> `optional` **yieldVal?**: `number`
Defined in: [js-xbbg/src/index.ts](https://github.com/underloam/xbbg/blob/main/js-xbbg/src/index.ts) (declaration: `index.d.ts:251`)