---
title: "How do I use Lumipy to interact with Luminesce?"
slug: "how-do-i-use-lumipy-to-interact-with-luminesce"
tags: ["lumipy"]
updated: 2025-01-06T16:28:11Z
published: 2025-01-06T16:28:11Z
canonical: "support.lusid.com/how-do-i-use-lumipy-to-interact-with-luminesce"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://support.lusid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How do I use Lumipy to interact with Luminesce?

Lumipy is a Python library that makes it easy to use Luminesce as part of the Python data science ecosystem, in particular [Pandas](https://pandas.pydata.org/) and [Jupyter](https://jupyter.org/).

Once installed and authenticated, and providing end users have sufficient access control permissions, they can interact with Luminesce using their familiar Python programming environment. [See all tools and interfaces to Luminesce](/v1/docs/what-tools-are-available-to-write-luminesce-queries).

## Installing Lumipy

[If you have previously used the v1 Lumipy SDK (dve-lumipy-preview), follow these steps to upgrade Lumipy to v2 of the SDK.](/v1/docs/how-do-i-use-lumipy-to-interact-with-luminesce#appendix-a-upgrading-to-the-v2-sdk)

To install Lumipy, run the following command:

```shell
pip install lumipy
```

For an installation which only installs the parts of Lumipy you specifically require, run the following command to download Lumipy without dependencies:

```shell
pip install lumipy --no-dependencies
```

You can then install the parts you require, for example:

```shell
pip install pandas luminesce-sdk
```

## Authenticating to Lumipy

As with any FINBOURNE SDK, you must obtain an [API access token](/v1/docs/what-are-an-api-access-token-and-a-client-secret). For Lumipy, we recommend authenticating using a [personal access token](/v1/docs/what-is-a-personal-access-token).

You can [follow these steps to obtain a personal access token](/v1/docs/how-do-i-create-or-revoke-a-long-lived-personal-access-token).

Once you have obtained a personal access token you must add it, alongside your LUSID domain, to your Lumipy configuration:

```python
import lumipy as lm
lm.config.add('<your-domain>', '<your-personal-access-token>')
```

If you want to add more than one domain, add each domain and personal access token to your Lumipy configuration and then set the domain you want to interact with:

```python
import lumipy as lm
lm.config.add('<your-other-domain>', '<your-personal-access-token>')
lm.config.domain = '<your-other-domain>'
```

## Sending a SQL query directly to Luminesce

The simplest way to work with Lumipy is to use the `client` object to send a [Luminesce SQL query](/v1/docs/understanding-the-luminesce-sql-query-syntax) directly to Luminesce.

For example, to use the [Lusid.Instrument.Equity](/v1/docs/lusidinstrumenttype-reader-providers) provider to retrieve the first five equity instruments mastered in LUSID as a Pandas dataframe:

```python
import lumipy as lm
client = lm.get_client()
df = client.run('select * from lusid.instrument.equity where Scope = \'default\' limit 5')
```

![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/2dedc29d-5a55-48c4-9b77-9e3ebc5656f1.png)

## Scripting queries using Python

The most powerful way to work with Lumipy is to use the `atlas` object to create a hub for exploring providers and scripting queries using Python instead of SQL.

For example, to use the `Lusid.Instrument.Equity` provider to retrieve the first five equity instruments mastered in LUSID as a Pandas dataframe:

```python
import lumipy as lm
atlas = lm.get_atlas()
instr_provider = atlas.lusid_instrument() 
query = instr_provider.select('*').limit(5)
df = query.go()
```

To upsert equity instruments to LUSID using the [Lusid.Instrument.Equity.Writer](/v1/docs/lusidinstrumenttypewriter-providers) provider, you might:

1. Read data into Pandas from a CSV file:

```python
import lumipy as lm
import pandas as pd
instr_df = pd.read_csv("data.csv", keep_default_na = False)
```

![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/a8afd404-b441-4ea0-bda9-121caa17d5c6.png)
2. Rename dataframe columns to align with expected provider column names, and add a column specifying an [instrument scope](/v1/docs/understanding-instrument-scopes):

```python
instr_df.rename(columns = {'Security': 'DisplayName', 'Internal_id': 'ClientInternal', 'Currency': 'DomCcy'}, inplace = True)
instr_df['Scope'] = 'MyProtectedInstrumentScope'
```

![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/88968810-4200-4220-b8e1-9a89035fbbb2.png)
3. Convert the dataframe to a [table variable](/v1/docs/understanding-the-luminesce-sql-query-syntax#variables) in preparation for upserting to LUSID:

```python
tv = lm.from_pandas(instr_df)
```

![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/cc87b93d-e151-418d-8454-4bff9ce47250.png)
4. Upsert to LUSID, showing the response to retrieve the [LUIDs](/v1/docs/what-is-a-lusid-instrument-id-or-luid) and check for errors:

```python
w = atlas.lusid_instrument_equity_writer(to_write = tv)
q = w.select('^')
q.go()
```

![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/235ff90b-d32a-4529-9953-3a9ae85bd0fb.png)

## Getting more information

Lumipy also contains a command line interface (CLI). You can view functions and help for the CLI using `--help`:

```shell
$ lumipy --help
```

For more information, refer to the [Lumipy PyPi page](https://pypi.org/project/lumipy/) or read the [User Guide](https://github.com/finbourne/lumipy-tutorial/blob/master/lumipy-talk.pdf). Note the User Guide is 23 pages in total, not all of it shown at once; keep clicking the **More Pages** button:

![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/bce4b8cf-de92-48d3-8b96-5c4bfa1082b3.png)

You can also work through these [Jupyter Notebook tutorials](https://github.com/finbourne/lumipy-tutorial/tree/master/notebooks/tutorials-filled).

Note these [statistical custom functions](/v1/docs/supported-functions-in-luminesce-sql-queries#statistical-custom-functions) are designed to be used with Lumipy.

[See how to use Lumipy to create your own data providers in Python.](/v1/docs/how-do-i-use-lumipy-to-create-data-providers-in-python)

## Appendix A: Upgrading to the v2 SDK

Lumipy utilises [v2 of the FINBOURNE SDKs](/v1/docs/upgrading-to-v2-sdks). If you have previously used v1 of the Lumipy SDK, you must follow these steps to upgrade to v2:

1. Run the following command to uninstall `dve-lumipy-preview`:

```shell
pip uninstall dve-lumipy-preview
```
2. Run the following command to install Lumipy and force update all Lumipy dependencies:

```shell
pip install --force-reinstall lumipy
```

> [!WARNING]
> Note
> 
> Using `--force-reinstall` could affect your other Python projects. If you prefer not to update all dependencies, you can omit it:
> 
> ```shell
> pip install lumipy
> ```

## Related

- [How do I use Lumipy to create data providers in Python?](/how-do-i-use-lumipy-to-create-data-providers-in-python.md)