### Install pysdmx with All Extras

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/start.md

Install pysdmx with all available extras for full functionality.

```bash
pip install pysdmx[all]
```

--------------------------------

### Install pysdmx using verified requirements.txt

Source: https://github.com/bis-med-it/pysdmx/blob/develop/compliance.md

Install pysdmx and its dependencies using a verified requirements file, ensuring license compliance by installing from source.

```bash
pip install -r verified-requirements.txt --no-binary :all:
```

--------------------------------

### Install pysdmx with --no-binary flag

Source: https://github.com/bis-med-it/pysdmx/blob/develop/compliance.md

Use this command to install pysdmx in a license-compliant manner. This ensures that all third-party components are installed from source.

```bash
pip install pysdmx --no-binary :all:
```

--------------------------------

### Install pysdmx Core

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/start.md

Install the core functionality of the pysdmx library using pip.

```bash
pip install pysdmx
```

--------------------------------

### Install pysdmx with XML Extra

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/start.md

Install pysdmx with the 'xml' extra to enable parsing of SDMX-ML messages.

```bash
pip install pysdmx[xml]
```

--------------------------------

### Initialize PandasConnector with BIS Endpoint

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/howto/dc.md

Initializes the PandasConnector for the BIS endpoint. Ensure pysdmx[data] is installed.

```python
from pysdmx.api.dc import Endpoints
from pysdmx.api.dc.pd import PandasConnector

conn = PandasConnector(Endpoints.BIS)
```

--------------------------------

### Generate verified requirements.txt

Source: https://github.com/bis-med-it/pysdmx/blob/develop/compliance.md

Generate a requirements file with fixed version numbers to prevent pip from automatically using later dependency versions. This aids in reproducible and compliant installations.

```bash
poetry export -f requirements.txt -o verified-requirements.txt
```

--------------------------------

### Initialize and Use RegistryMaintenanceClient

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/api/fmr/maintenance.md

Demonstrates how to initialize the RegistryMaintenanceClient with target endpoint, user credentials, and then use it to upload a codelist structure.

```python
>>> from pysdmx.api.fmr.maintenance import RegistryMaintenanceClient
>>> cd = Code("A", name="Code A")
>>> cl = Codelist("CL_TEST", agency="TEST", name="Test CL", items=[cd])
>>> target = "https://registry.sdmx.org"
>>> client = RegistryMaintenanceClient(target, "user", "password")
>>> client.put_structures([cl])
```

--------------------------------

### Define Paths to SDMX Files

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/howto/vtl_handling.md

Set up the file paths for SDMX data and structure XML files. Ensure the paths are correctly resolved relative to the script's location.

```python
from pathlib import Path

# Path to the structures file (same directory as this script)
path_to_structures = Path(__file__).parent / "structures.xml"

# Path to the data file (same directory as this script)
path_to_data = Path(__file__).parent / "data.xml"
```

--------------------------------

### Connect to FMR Instance

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/howto/maintenance.md

Instantiate the RegistryMaintenanceClient by providing the FMR endpoint and user credentials. Ensure the user has write access to the FMR.

```python
from pysdmx.api.fmr.maintenance import RegistryMaintenanceClient

target = "https://registry.sdmx.org"
user = "your_username"
pwd = "your_password"

client = RegistryMaintenanceClient(target, user, pwd)
```

--------------------------------

### Get Categories for Dataflows

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/howto/structure_fs.md

Retrieve categories from the registry to identify dataflows for filesystem structuring.

```python
cs = await client.get_categories("MY_AGENCY", "MY_CATEGORY_SCHEME")
```

--------------------------------

### Initialize and use AsyncRegistryClient

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/api/fmr/async.md

Demonstrates how to initialize the AsyncRegistryClient with an API endpoint and retrieve a schema definition asynchronously. Ensure asyncio is imported and used to run the asynchronous function.

```python
>>> import asyncio
>>> from pysdmx.api.fmr import AsyncRegistryClient
>>> async def main():
>>>     gr = AsyncRegistryClient("https://registry.sdmx.org/sdmx/v2/")
>>>     mapping = await gr.get_schema("dataflow", "UIS", "EDUCAT_CLASS_A", "1.0")
>>>     print(mapping)
>>> asyncio.run(main())
```

--------------------------------

### Read SDMX Structures from a File

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/howto/io_structure.md

Reads an SDMX Structures message from a specified file path. Ensure the pysdmx[xml] extra is installed for SDMX-ML support.

```python
from pysdmx.io import read_sdmx
from pathlib import Path

# Read file from the same folder as this code
file_path = Path(__file__).parent / "structure.xml"

message = read_sdmx(file_path)
# Access the structures of the SDMX Structures message
structures = message.structures
```

--------------------------------

### Instantiate AsyncRegistryClient

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/howto/config.md

Connect to an SDMX Registry using the asynchronous client. Pass the SDMX-REST endpoint of your target Registry.

```python
from pysdmx.api.fmr import AsyncRegistryClient

client = AsyncRegistryClient("[endpoint_comes_here]")
```

--------------------------------

### Get Transformation Scheme

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/howto/toolkit/vtl_toolkit.md

Extract a specific Transformation Scheme from the message object using its identifier. This object contains references to Ruleset Schemes and User Defined Operator Schemes.

```python
transformation_scheme = msg.get_transformation_scheme("TransformationScheme=FR1:BPE_CENSUS(1.0)")
```

--------------------------------

### Create Provider Folders within Dataflow Folders

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/howto/structure_fs.md

Create subdirectories for each provider within their respective dataflow folders, ensuring the dataflow folder exists first.

```python
import os
for flow, providers in flow_provs.items():
    if os.path.exists(flow):
        for provider in providers:
            os.mkdir(f"{flow}/{provider}")
```

--------------------------------

### Create a Value Map

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/api/model/map.md

Demonstrates how to create a simple value map to translate a 2-letter ISO country code to a 3-letter ISO country code. This is useful for direct value transformations.

```python
>>> ValueMap("BE", "BEL")
```

--------------------------------

### Write SDMX Data to a File (CSV)

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/howto/io_data.md

Use `write_sdmx` to write data from a PandasDataset to a file. Ensure the `pysdmx[data]` extra is installed. For SDMX-ML, `pysdmx[xml]` is also required.

```python
from pysdmx.io import write_sdmx
from pysdmx.io.format import Format
from pysdmx.io.pd import PandasDataset

# Replace with actual structure and data
dataset = PandasDataset(structure=..., data=...)

write_sdmx(
    dataset,
    output_path="output.csv",
    sdmx_format=Format.DATA_SDMX_CSV_2_0_0,
)
```

--------------------------------

### Validating Data Types

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/howto/validate.md

Attempts to cast values to their expected data types (e.g., float for DOUBLE/FLOAT) and raises a TypeError for invalid conversions. This example uses basic Python type casting.

```python
from pysdmx.model import DataType
for row in reader:
    for comp, value in row.items():
        data_type = schema.components[comp].dtype
        if data_type in [DataType.DOUBLE, DataType.FLOAT]:
            try:
                float(value)
            except ValueError:
                raise TypeError(f"{value} for component {comp} is not a valid {data_type}")
```

--------------------------------

### Select Specific Columns with pysdmx

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/howto/dc.md

Use the 'columns' parameter to specify which columns to include in the resulting DataFrame. This is useful for reducing DataFrame size and focusing on relevant data. The example shows selecting 'OBS_VALUE' and 'OBS_STATUS'.

```python
df = conn.data(cbs, "L_POSITION = 'D' AND L_REP_CTY = 'CH'", columns=["OBS_VALUE", "OBS_STATUS"])

print(df)

# Output:
#                                         OBS_STATUS   OBS_VALUE
# SERIES_KEY                 TIME_PERIOD
# Q.S.CH.4R.U.D.A.A.TO1.A.5J 2005-Q2      A            805455.0
#                            2005-Q3      A            847949.0
#                            2005-Q4      A            794753.0
#                            2006-Q1      A            919947.0
#                            2006-Q2      A            989307.0
# [164 rows x 2 columns]
```

--------------------------------

### Connect to an SDMX Registry

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/howto/structure_db.md

Instantiate the asynchronous client by providing the SDMX-REST endpoint of your Registry. This is necessary to interact with the registry and retrieve metadata.

```python
from pysdmx.api.fmr import AsyncRegistryClient
client = AsyncRegistryClient("https://registry.sdmx.org/sdmx/v2/")
```

--------------------------------

### Run VTL Script with vtlengine

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/howto/vtl_handling.md

Execute a VTL script using the run_sdmx method from the vtlengine library. Pass the transformation scheme, datasets, and dataflow mappings as arguments to process the data.

```python
from vtlengine import run_sdmx

# Run the VTL script with the datasets and the dataflow mapping
run_sdmx(script=ts, datasets=datasets, mappings=dataflow_mapping)
```

--------------------------------

### Connect to SDMX Registry

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/howto/validate.md

Instantiate the AsyncRegistryClient to connect to an SDMX Registry. Pass the SDMX-REST endpoint URL of the Registry.

```python
from pysdmx.api.fmr import AsyncRegistryClient
gr = AsyncRegistryClient("https://registry.sdmx.org/sdmx/v2/")
```

--------------------------------

### Initialize and Use Synchronous GDS Client

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/api/gds/sync.md

Instantiate the GdsClient for synchronous data retrieval and fetch agency information.

```python
from pysdmx.api.gds import GdsClient
gc = GdsClient()
agencies = gc.get_agencies("BIS")
```

--------------------------------

### Basic Asynchronous GDS Agency Retrieval

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/api/gds/async.md

Demonstrates how to initialize the AsyncGdsClient and retrieve agencies asynchronously using Python's asyncio.

```python
import asyncio
from pysdmx.api.gds import AsyncGdsClient

async def main():
    gr = AsyncGdsClient()
    gds_agencies = await gr.get_agencies("BIS")
    print(gds_agencies)
asyncio.run(main())
```

--------------------------------

### Convert SDMX-ML to SDMX-CSV

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/howto/io_data.md

Use get_datasets to read SDMX-ML data and structures, then write_sdmx to convert it to SDMX-CSV 2.0. Ensure the correct Format enum is specified.

```python
from pysdmx.io import get_datasets, write_sdmx
from pathlib import Path
from pysdmx.io.format import Format

# Read the data and structures SDMX-ML messages (any supported format can be used)
datasets = get_datasets("data.xml", "structures.xml")

# Write the data to SDMX-CSV 2.0
write_sdmx(
    sdmx_objects=datasets,
    sdmx_format=Format.DATA_SDMX_CSV_2_0_0,
    output_path="output.csv",
)
```

--------------------------------

### Create and Upload Codelist

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/howto/maintenance.md

Manually create a simple codelist with codes and then upload it to the FMR. The owning agency must exist in the FMR, and the user needs upload permissions for that agency.

```python
from pysdmx.model import Code, Codelist

cd = Code("A", name="Code A")
cl = Codelist("CL_TEST", agency="TEST", name="Test CL", items=[cd])
```

```python
client.put_structures([cl])
```

--------------------------------

### List Available Dataflows

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/howto/dc.md

Use the `dataflows` method to list all available dataflows. This is the first step in identifying datasets of interest.

```python
flows = conn.dataflows()
print(f"Found {len(flows)} dataflows.")
for f in flows:
    print(f.short_urn)

# Output:
# Found 32 dataflows.
# Dataflow=BIS:BIS_REL_CAL(1.0)
# Dataflow=BIS:WS_CBPOL(1.0)
# Dataflow=BIS:WS_CBS_PUB(1.0)
# Dataflow=BIS:WS_CBTA(1.0)
# Dataflow=BIS:WS_CPMI_CASHLESS(1.0)
# ... more lines
```

--------------------------------

### Create Dataflow Folders

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/howto/structure_fs.md

Iterate through dataflows obtained from a category scheme and create a directory for each dataflow ID using os.mkdir.

```python
import os
for flow in cs.dataflows:
    os.mkdir(flow.id)
```

--------------------------------

### Read Transformation Scheme and VTL Mapping from File

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/howto/vtl_handling.md

Load transformation schemes and VTL mappings from an SDMX XML file using read_sdmx. This method allows for external definition of VTL logic.

```python
from pysdmx.io import read_sdmx
from pathlib import Path
# Path to the transformation file
path_to_vtl_ts = Path(__file__).parent / "vtl_ts.xml"

# Read the transformation file with read_sdmx
message = read_sdmx(path_to_vtl_ts)

# Get the Transformation Schemes
ts = message.get_transformation_schemes()[0]
# Get the VTL Mapping Scheme
mapping_scheme = message.get_vtl_mapping_schemes()[0]
# Get the VTL Dataflow Mapping from the items, assuming the first item is the one we want
dataflow_mapping = mapping_scheme.items[0]
```

--------------------------------

### Create and Upload Metadata Report

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/howto/maintenance.md

Define a metadata report including attributes and targets, then upload it to the FMR. Ensure the necessary metadata models are imported.

```python
from pysdmx.model import MetadataAttribute, MetadataReport

attr = Attribute("A", "My attribute")
report = MetadataReport(
    "MR_TEST",
    agency="TEST",
    name="Test Report",
    attributes=[attr],
    targets=[
        "urn:sdmx:org.sdmx.infomodel.datastructure.Dataflow=TS:T1(1.0)"
    ]
)
```

```python
client.put_metadata_reports([report])
```

--------------------------------

### registration

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/api/query/service.md

Execute a registration query against the service.

```APIDOC
## registration(query: RegistrationByContextQuery | RegistrationByIdQuery | RegistrationByProviderQuery) -> bytes

### Description
Execute a registration query against the service.

### Parameters
* **query** (RegistrationByContextQuery | RegistrationByIdQuery | RegistrationByProviderQuery) - The registration query object.
```

--------------------------------

### Read SDMX Datasets and Structures

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/howto/vtl_handling.md

Use the get_datasets function to load both data and its associated structures into a single Pandas Dataset. This is the recommended method for seamless data and structure handling.

```python
from pysdmx.io import get_datasets
# With the data and metadata path we extract the datasets with their related structures
datasets = get_datasets(path_to_data, path_to_structures)
```

--------------------------------

### Construct and Print Role Information

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/howto/structure_fs.md

Generate role information including ID, name, and approver based on dataflow and agency contact details. This serves as a precursor to creating roles in a directory service.

```python
# Get extended information about the sub-agencies
agencies = await client.get_agencies("MY_AGENCY")

# Organize the agencies as a map for quick lookup
agency_map = {a.id: a for a in agencies}

# Assume that the role of the person approving access requests is "APPROVER"
for flow in cs.dataflows:
    for access in ["RO", "RW"]:
        # Fetch the contact responsible for approving access requests
        contact = [c for c in agency_map[flow.agency].contacts if c.role == "APPROVER"][0]

        # Construct role information
        role = {
            "id": f"R_MYAPP_{flow.id}_{access}",
            "name": f"{access} access to {flow.id} ({flow.name})",
            "approver": contact.id
        }

        # Print the role information (actual implementation will involve creating roles in the directory service)
        print(role)
```

--------------------------------

### Generate TransformationScheme from VTL Script

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/howto/generate_ts.md

Use the `generate_sdmx` function from the `vtlengine` library to create a TransformationScheme object. You must provide the VTL script content, agency ID, scheme ID, and version.

```python
from vtlengine import generate_sdmx

# Generate a Transformation Scheme from the VTL script
ts_scheme = generate_sdmx(script=vtl_script, agency_id="MD", id="TS1", version="1.0")

print(repr(ts_scheme))

```

--------------------------------

### RegistryClient.get_codes

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/api/fmr/sync.md

Retrieves a codelist or valuelist based on agency, ID, and version.

```APIDOC
## get_codes(agency: str, id: str, version: str = '~')

### Description
Get the codelist or valuelist matching the supplied parameters.

### Method
`get_codes`

### Parameters
#### Path Parameters
- **agency** (str) - Required - The agency maintaining the codelist.
- **id** (str) - Required - The ID of the codelist to be returned.
- **version** (str) - Optional - The version of the codelist to be returned. The most recent version will be returned, unless specified otherwise.

### Returns
Codelist - The requested codelist.
```

--------------------------------

### Download Data with SQL String Filter

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/howto/dc.md

Download data by providing query filters as a SQL-like string. This is an alternative to using pysdmx filter objects.

```python
df = conn.data(cbs, "L_POSITION = 'D' AND L_REP_CTY = 'CH'")
```

--------------------------------

### Write SDMX Structures with Custom Header and Pretty Print

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/howto/io_structure.md

Writes a DataStructureDefinition to an XML file with a custom header and pretty-printed output. Requires the pysdmx[xml] extra.

```python
from datetime import datetime

from pysdmx.io import write_sdmx
from pysdmx.io.format import Format
from pysdmx.model import DataStructureDefinition, Organisation

from pysdmx.model.message import Header

dsds = DataStructureDefinition(id=..., name=..., components=...)
header = Header(
    id="TEST_MESSAGE",
    test=True,
    prepared=datetime.now(),
    sender=Organisation(id="MD", name="MeaningfulData"),
)

write_sdmx(
    dsds,
    output_path="output.xml",
    sdmx_format=Format.DATA_SDMX_ML_3_0,
    prettyprint=True,
    header=header,
)
```

--------------------------------

### Download Data with MultiFilter

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/howto/dc.md

Use MultiFilter to apply multiple query conditions when downloading data. Ensure necessary imports are present.

```python
from pysdmx.api.dc.query import MultiFilter, Operator, TextFilter

f1 = TextFilter("L_POSITION", Operator.EQUALS, "D")
f2 = TextFilter("L_REP_CTY", Operator.EQUALS, "CH")
mf = MultiFilter([f1, f2])

df = conn.data(cbs, mf)

print(df)
```

--------------------------------

### Generate SQL CREATE TABLE Statement from SDMX Dataflow

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/howto/toolkit/sqlsrv_toolkit.md

Use this function to generate a SQL CREATE TABLE statement based on the structural metadata of an SDMX dataflow. It automatically defines columns, primary keys, and indexes based on the dataflow's dimensions. Additional parameters allow customization of table naming, schema, and the inclusion of extra columns.

```python
from pysdmx.api.fmr import RegistryClient
from pysdmx.toolkit.sqlsrv import create_table

client = RegistryClient("https://registry.sdmx.org/sdmx/v2")
dfi = client.get_dataflow_details("SDMX", "NAMAIN_IDC_N", "1.0")
cs = create_table(dfi)

print(cs)

# Outputs
# CREATE TABLE dbo.NAMAIN_IDC_N (
#    FREQ CHAR(1) NOT NULL, -- Frequency
#    ADJUSTMENT NVARCHAR(2) NOT NULL, -- Adjustment indicator
#    REF_AREA NVARCHAR(5) NOT NULL, -- Reference area
#    COUNTERPART_AREA NVARCHAR(5) NOT NULL, -- Counterpart area
#    REF_SECTOR NVARCHAR(7) NOT NULL, -- Reporting institutional sector
#    COUNTERPART_SECTOR NVARCHAR(7) NOT NULL, -- Counterpart institutional sector
#    ACCOUNTING_ENTRY NVARCHAR(2) NOT NULL, -- Accounting Entry
#    STO NVARCHAR(9) NOT NULL, -- Stocks, Transactions, Other Flows
#    INSTR_ASSET NVARCHAR(7) NOT NULL, -- Instrument and Assets Classification
#    ACTIVITY NVARCHAR(9) NOT NULL, -- Activity classification
#    EXPENDITURE NVARCHAR(12) NOT NULL, -- Expenditure (COFOG, COICOP, COPP or COPNI)
#    UNIT_MEASURE NVARCHAR(15) NOT NULL, -- Unit
#    PRICES NVARCHAR(2) NOT NULL, -- Prices
#    TRANSFORMATION NVARCHAR(5) NOT NULL, -- Transformation
#    TIME_PERIOD NVARCHAR(50) NOT NULL, -- Time period
#    OBS_VALUE FLOAT NULL, -- Observation value
#    COMMENT_OBS NVARCHAR(4000) NULL, -- Comments to the observation value
#    CONF_STATUS CHAR(1) NOT NULL, -- Confidentiality status
#    EMBARGO_DATE DATETIME2 NULL, -- Embargo date
#    OBS_STATUS CHAR(1) NOT NULL, -- Observation status
#    PRE_BREAK_VALUE FLOAT NULL, -- Pre-break value
#    COMMENT_TS NVARCHAR(1050) NULL, -- Series comment
#    COMPILING_ORG NVARCHAR(4) NULL, -- Compiling organisation
#    CURRENCY NVARCHAR(15) NULL, -- Currency code used for compilation
#    DATA_COMP NVARCHAR(4000) NULL, -- Underlying compilation
#    DECIMALS NVARCHAR(2) NOT NULL, -- Decimals
#    DISS_ORG NVARCHAR(MAX) NULL, -- Dissemination organisation
#    LAST_UPDATE DATETIME2 NULL, -- Last Update Date
#    REF_PERIOD_DETAIL NVARCHAR(3) NULL, -- Reference period detail
#    REF_YEAR_PRICE INT NULL, -- Reference year (price)
#    TABLE_IDENTIFIER NVARCHAR(12) NULL, -- Table identifier
#    REF_PERIOD_DETAIL NVARCHAR(3) NULL, -- Reference period detail
#    REF_YEAR_PRICE INT NULL, -- Reference year (price)
#    TABLE_IDENTIFIER NVARCHAR(12) NULL, -- Table identifier
#    TIME_FORMAT NVARCHAR(4) NOT NULL, -- Time format
#    TIME_PER_COLLECT CHAR(1) NULL, -- Time period collection
#    TITLE NVARCHAR(200) NULL, -- Title
#    UNIT_MULT NVARCHAR(2) NOT NULL, -- Unit multiplier
#    CONSTRAINT PK_dbo_NAMAIN_IDC_N PRIMARY KEY (FREQ,ADJUSTMENT,REF_AREA,COUNTERPART_AREA,REF_SECTOR,COUNTERPART_SECTOR,ACCOUNTING_ENTRY,STO,INSTR_ASSET,ACTIVITY,EXPENDITURE,UNIT_MEASURE,PRICES,TRANSFORMATION,TIME_PERIOD)
# );
# CREATE INDEX IDX_dbo_NAMAIN_IDC_N_FREQ ON dbo.NAMAIN_IDC_N (FREQ);
# CREATE INDEX IDX_dbo_NAMAIN_IDC_N_ADJUSTMENT ON dbo.NAMAIN_IDC_N (ADJUSTMENT);
# CREATE INDEX IDX_dbo_NAMAIN_IDC_N_REF_AREA ON dbo.NAMAIN_IDC_N (REF_AREA);
# CREATE INDEX IDX_dbo_NAMAIN_IDC_N_COUNTERPART_AREA ON dbo.NAMAIN_IDC_N (COUNTERPART_AREA);
# CREATE INDEX IDX_dbo_NAMAIN_IDC_N_REF_SECTOR ON dbo.NAMAIN_IDC_N (REF_SECTOR);
# CREATE INDEX IDX_dbo_NAMAIN_IDC_N_COUNTERPART_SECTOR ON dbo.NAMAIN_IDC_N (COUNTERPART_SECTOR);
# CREATE INDEX IDX_dbo_NAMAIN_IDC_N_ACCOUNTING_ENTRY ON dbo.NAMAIN_IDC_N (ACCOUNTING_ENTRY);
# CREATE INDEX IDX_dbo_NAMAIN_IDC_N_STO ON dbo.NAMAIN_IDC_N (STO);
# CREATE INDEX IDX_dbo_NAMAIN_IDC_N_INSTR_ASSET ON dbo.NAMAIN_IDC_N (INSTR_ASSET);
# CREATE INDEX IDX_dbo_NAMAIN_IDC_N_ACTIVITY ON dbo.NAMAIN_IDC_N (ACTIVITY);
# CREATE INDEX IDX_dbo_NAMAIN_IDC_N_EXPENDITURE ON dbo.NAMAIN_IDC_N (EXPENDITURE);
# CREATE INDEX IDX_dbo_NAMAIN_IDC_N_UNIT_MEASURE ON dbo.NAMAIN_IDC_N (UNIT_MEASURE);
# CREATE INDEX IDX_dbo_NAMAIN_IDC_N_PRICES ON dbo.NAMAIN_IDC_N (PRICES);
# CREATE INDEX IDX_dbo_NAMAIN_IDC_N_TRANSFORMATION ON dbo.NAMAIN_IDC_N (TRANSFORMATION);
# CREATE INDEX IDX_dbo_NAMAIN_IDC_N_TIME_PERIOD ON dbo.NAMAIN_IDC_N (TIME_PERIOD);

```

--------------------------------

### AsyncGdsClient.get_sdmx_apis

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/api/gds/async.md

Retrieves a list of available SDMX API versions asynchronously. Allows filtering by a specific API version.

```APIDOC
## async get_sdmx_apis(api_version: str = '\*') -> Sequence[GdsSdmxApi]

### Description
Get the list of SDMX API versions asynchronously.

### Method
async

### Parameters
#### Path Parameters
- **api_version** (str) - Optional - Defaults to '\*'. The specific API version to retrieve.

### Response
#### Success Response
- **Sequence[GdsSdmxApi]** - The requested list of SDMX APIs.
```

--------------------------------

### schema

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/api/query/service.md

Execute a schema query against the service.

```APIDOC
## schema(query: SchemaQuery) -> bytes

### Description
Execute a schema query against the service.

### Parameters
* **query** (SchemaQuery) - The schema query object.
```

--------------------------------

### put_structures

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/api/fmr/maintenance.md

Uploads SDMX structures to the FMR. This method is experimental and subject to change.

```APIDOC
## put_structures

### Description
Uploads SDMX structures to the FMR. This method is experimental and its interface or behavior may change without notice.

### Method
POST (inferred)

### Endpoint
/structures (inferred)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **artefacts** (Sequence[MaintainableArtefact]) - Required - The sequence of SDMX maintainable artefacts to upload.
- **header** (Header | None) - Optional - SDMX Header to include in the message. If not supplied, pysdmx will generate one.
- **action** (StructureAction) - Optional - How to apply the changes in case of already existing structures. Defaults to StructureAction.Replace.

### Request Example
```python
# Example usage (actual request body structure depends on MaintainableArtefact and Header models)
client.put_structures(artefacts=my_structures, header=my_header, action=StructureAction.Replace)
```

### Response
#### Success Response (200)
None (inferred)

#### Response Example
None
```

--------------------------------

### Create VTL Mapping and Transformation Scheme Objects

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/howto/vtl_handling.md

Instantiate VTL mapping and transformation scheme objects directly in Python code. This is useful for dynamic VTL script generation or when not using external files.

```python
from pysdmx.model import VtlDataflowMapping, DataflowRef, VtlMappingScheme, TransformationScheme, Transformation

# Mapping using VTLDataflowMapping object:
dataflow_mapping = VtlDataflowMapping(
    dataflow=DataflowRef(agency="MD", id="TEST_DF", version="1.0"),
    dataflow_alias="DS_1",
    id="VTL_MAP_1",
    name="VTL Mapping 1",
)
mapping_scheme = VtlMappingScheme(
    id="VTL_MAP_SCHEME_1",
    name="VTL Mapping Scheme 1",
    version="1.0",
    agency="MD",
    items=[dataflow_mapping],
)

# Transformation Scheme object
ts = TransformationScheme(
    id="TS1",
    version="1.0",
    agency="MD",
    vtl_version="2.1",
    name="Transformation Scheme 1",
    items=[
        Transformation(
            id="T1",
            uri=None,
            urn=None,
            name="Transformation 1",
            description=None,
            expression="DS_1 [calc Me_4 := OBS_VALUE]",
            is_persistent=True,
            result="DS_r",
            annotations=(),
        ),
    ],
    vtl_mapping_scheme=mapping_scheme
)
```

--------------------------------

### AsyncGdsClient.get_services

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/api/gds/async.md

Retrieves a list of services based on supplied parameters asynchronously. Supports filtering by service name, resource, and version.

```APIDOC
## async get_services(service: str, resource: str = '\*', version: str = '\*') -> Sequence[GdsService]

### Description
Get a list of services for the supplied params asynchronously.

### Method
async

### Parameters
#### Path Parameters
- **service** (str) - Required - The name of the service.
- **resource** (str) - Optional - Defaults to '\*'. The resource to filter by.
- **version** (str) - Optional - Defaults to '\*'. The version to filter by.

### Response
#### Success Response
- **Sequence[GdsService]** - The requested list of services.
```

--------------------------------

### Organize Dataflows by Provider

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/howto/structure_fs.md

Collect providers for each dataflow, mapping dataflow IDs to a set of provider IDs. This prepares for creating nested provider folders.

```python
from collections import defaultdict
flow_provs = defaultdict(set)
providers = client.get_providers("MY_AGENCY", True)
for prov in providers:
    for flow in prov.dataflows:
        flow_provs[flow.id].add(prov.id)
```

--------------------------------

### RegistryClient.get_categorisation

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/api/fmr/sync.md

Retrieves a categorisation based on agency, ID, and version.

```APIDOC
## get_categorisation(agency: str, id: str, version: str = '~')

### Description
Get the categorisation matching the supplied parameters.

### Method
`get_categorisation`

### Parameters
#### Path Parameters
- **agency** (str) - Required - The agency maintaining the categorisation.
- **id** (str) - Required - The ID of the categorisation to be returned.
- **version** (str) - Optional - The version of the categorisation to be returned. The most recent version will be returned, unless specified otherwise.

### Returns
Categorisation - The requested categorisation.
```

--------------------------------

### RulesetScheme

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/api/model/vtl.md

A collection of rulesets for VTL transformations.

```APIDOC
## class pysdmx.model.vtl.RulesetScheme

### Description
A collection of rulesets.

### Parameters
- **id** (str) - Required - Identifier for the ruleset scheme.
- **uri** (str | None) - Optional - Uniform Resource Identifier for the scheme.
- **urn** (str | None) - Optional - Uniform Resource Name for the scheme.
- **name** (str | None) - Optional - Name of the scheme.
- **description** (str | None) - Optional - Description of the scheme.
- **version** (str) - Optional - Version of the scheme (default: '1.0').
- **valid_from** (datetime | None) - Optional - The date from which the scheme is valid.
- **valid_to** (datetime | None) - Optional - The date until which the scheme is valid.
- **is_final** (bool) - Optional - Whether the scheme is final (default: False).
- **is_external_reference** (bool) - Optional - Whether the scheme is an external reference (default: False).
- **service_url** (str | None) - Optional - URL for the service.
- **structure_url** (str | None) - Optional - URL for the structure.
- **agency** (str | Agency) - Optional - The agency that maintains the scheme.
- **items** (Sequence[Ruleset]) - Optional - A sequence of rulesets.
- **is_partial** (bool) - Optional - Whether the scheme is partial (default: False).
- **vtl_version** (str | None) - Optional - The VTL version associated with the scheme.
- **vtl_mapping_scheme** (str | VtlMappingScheme | Reference | None) - Optional - The VTL mapping scheme associated with the ruleset scheme.
- **annotations** (Sequence[Annotation]) - Optional - A sequence of annotations.
```

--------------------------------

### Combine Data with Metadata

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/howto/io_data.md

Use get_datasets to combine SDMX data with its related metadata. This is essential for data validation, time series serialization, and VTL validations.

```python
from pysdmx.io import get_datasets

datasets = get_datasets(data_path, metadata_path)
```

--------------------------------

### Execute SDMX-REST Query

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/howto/sdmx_rest.md

Instantiate RestService with the endpoint URL and API version to execute a query. The service object handles sending the query to the SDMX-REST service and receiving the response.

```python
from pysdmx.api.qb import ApiVersion, RestService

endpoint = "https://registry.sdmx.org/sdmx/v2/"
version = ApiVersion.V2_0_0
service = RestService(endpoint, version)
resp = service.structure(query)
```

--------------------------------

### structure

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/api/query/service.md

Execute a structure query against the service.

```APIDOC
## structure(query: StructureQuery) -> bytes

### Description
Execute a structure query against the service.

### Parameters
* **query** (StructureQuery) - The structure query object.
```

--------------------------------

### VtlConceptMapping

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/api/model/vtl.md

Represents a single mapping with a concept. It includes an ID, optional URI and URN, name, description, and details about the associated concept.

```APIDOC
## Class pysdmx.model.vtl.VtlConceptMapping

### Description
Represents a single mapping with a concept. It includes an ID, optional URI and URN, name, description, and details about the associated concept.

### Parameters
- **id** (str) - Required - The identifier for the mapping.
- **uri** (str | None) - Optional - The URI of the mapping.
- **urn** (str | None) - Optional - The URN of the mapping.
- **name** (str | None) - Optional - The name of the mapping.
- **description** (str | None) - Optional - The description of the mapping.
- **concept** (str | [Concept](concept.md#pysdmx.model.concept.Concept) | [ItemReference](../helper/urn.md#pysdmx.util.ItemReference)) - Required - The concept associated with the mapping.
- **concept_alias** (str) - Required - An alias for the concept.
- **annotations** (Sequence[Annotation]) - Optional - A sequence of annotations.
```

--------------------------------

### Print Basic Dataflow Information

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/howto/dc.md

Display fundamental details of a dataflow, such as its name and the total number of series it contains.

```python
print(f"Name: {cbs.name}")
print(f"Number of series: {cbs.series_count}")

# Output:
# Name: Consolidated banking
# Number of series: 227004
```

--------------------------------

### RegistrationByProviderQuery

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/api/query/registration.md

A query for registrations filtered by provider details.

```APIDOC
## Class pysdmx.api.qb.registration.RegistrationByProviderQuery

### Description
A query for registrations filtered by provider details. Allows filtering by provider agency ID, provider ID, and update timestamps.

### Parameters
#### Path Parameters
None

#### Query Parameters
* **provider_agency_id** (str | Sequence[str]) - Optional - The ID of the agency maintaining the data provider scheme. Defaults to '*'.
* **provider_id** (str | Sequence[str]) - Optional - The provider of the registered data. Defaults to '*'.
* **updated_before** (datetime | None) - Optional - Returns only registrations updated or created before the supplied timestamp.
* **updated_after** (datetime | None) - Optional - Returns only registrations updated or created after the supplied timestamp.

### Request Example
None explicitly provided in source.

### Response
None explicitly provided in source.

#### Success Response (200)
None explicitly provided in source.

#### Response Example
None explicitly provided in source.
```

--------------------------------

### Download Data with Label Names

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/howto/dc.md

Retrieve data and display category field names instead of their IDs by setting the 'labels' parameter to 'name'. This provides more human-readable output.

```python
df = conn.data(cbs, "L_POSITION = 'D' AND L_REP_CTY = 'CH'", labels="name")

print(df)
```

--------------------------------

### Define Basic MultiValueMap

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/api/model/map.md

Creates a MultiValueMap to map a source value (e.g., local currency code) to a target value (e.g., ISO currency code) for a specific country.

```python
>>> MultiValueMap(["DE", "LC"], ["EUR"])
>>> MultiValueMap(["CH", "LC"], ["CHF"])
```

--------------------------------

### VtlMapping

Source: https://github.com/bis-med-it/pysdmx/blob/develop/docs/api/model/vtl.md

Represents a single VTL mapping. It includes an ID, optional URI and URN, name, and description.

```APIDOC
## Class pysdmx.model.vtl.VtlMapping

### Description
Represents a single VTL mapping. It includes an ID, optional URI and URN, name, and description.

### Parameters
- **id** (str) - Required - The identifier for the mapping.
- **uri** (str | None) - Optional - The URI of the mapping.
- **urn** (str | None) - Optional - The URN of the mapping.
- **name** (str | None) - Optional - The name of the mapping.
- **description** (str | None) - Optional - The description of the mapping.
- **annotations** (Sequence[Annotation]) - Optional - A sequence of annotations.
```