> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-postgresql-tls-support.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# catálogo REST

> En esta guía, le mostraremos cómo consultar sus datos con ClickHouse y el catálogo REST.

export const galaxyOnClick = eventName => () => {
  try {
    if (typeof window !== "undefined" && window.galaxy && eventName) {
      window.galaxy.track(eventName, {
        interaction: "click"
      });
    }
  } catch (e) {}
};

export const BetaBadge = ({link, galaxyTrack, galaxyEvent}) => {
  if (link) {
    return <a href={link} target="_blank" rel="noopener noreferrer" className="betaBadge" onClick={galaxyTrack && galaxyEvent ? galaxyOnClick(galaxyEvent) : undefined}>
                <Icon />
                <span>Beta</span>
            </a>;
  }
  return <div className="betaBadge">
            <Icon />
            <span>
                Funcionalidad beta. 
                <u>
                    <a href="/docs/beta-and-experimental-features#beta-features">
                        Más información.
                    </a>
                </u>
            </span>
        </div>;
};

<Note>
  La integración con el REST Catalog funciona solo con tablas Iceberg.
  Esta integración es compatible tanto con AWS S3 como con otros proveedores de almacenamiento en la nube.
</Note>

ClickHouse admite la integración con múltiples catálogos (Unity, Glue, REST, Polaris, etc.). En esta guía se explica cómo consultar sus datos con ClickHouse y la especificación [REST Catalog](https://github.com/apache/iceberg/blob/main/open-api/rest-catalog-open-api.yaml/).

El REST Catalog es una especificación de API estandarizada para catálogos Iceberg, compatible con varias plataformas, entre ellas:

* **Entornos de desarrollo local** (con configuraciones de docker-compose)
* **Servicios gestionados** como Tabular.io
* **Implementaciones self-hosted** de REST Catalog

<Note>
  Como esta funcionalidad está en beta, deberá habilitarla con:
  `SET allow_database_iceberg = 1;`
</Note>

<div id="local-development-setup">
  ## Configuración para desarrollo local
</div>

Para el desarrollo y las pruebas locales, puedes usar una configuración de catálogo REST basada en contenedores. Este enfoque es ideal para el aprendizaje, la creación de prototipos y los entornos de desarrollo.

<div id="local-prerequisites">
  ### Requisitos previos
</div>

1. **Docker and Docker Compose**: Asegúrate de que Docker esté instalado y en funcionamiento
2. **Configuración de ejemplo**: Puedes usar varias configuraciones de docker-compose (consulta las imágenes de Docker alternativas más abajo)

<div id="setting-up-local-rest-catalog">
  ### Configuración de un catálogo REST local
</div>

Puede usar varias implementaciones de catálogo REST en contenedores, como **[Databricks docker-spark-iceberg](https://github.com/databricks/docker-spark-iceberg/blob/main/docker-compose.yml?ref=blog.min.io)**, que proporciona un entorno completo de Spark + Iceberg + catálogo REST con docker-compose, por lo que resulta ideal para probar integraciones con Iceberg.

**Paso 1:** Cree una carpeta nueva en la que ejecutar el ejemplo y, a continuación, cree un archivo `docker-compose.yml` con la configuración de [Databricks docker-spark-iceberg](https://github.com/databricks/docker-spark-iceberg/blob/main/docker-compose.yml?ref=blog.min.io).

**Paso 2:** A continuación, cree un archivo `docker-compose.override.yml` y añada en él la siguiente configuración del contenedor de ClickHouse:

```yaml theme={null}
version: '3.8'

services:
  clickhouse:
    image: clickhouse/clickhouse-server:25.5.6
    container_name: clickhouse
    user: '0:0'  # Garantiza permisos de root
    ports:
      - "8123:8123"
      - "9002:9000"
    volumes:
      - ./clickhouse:/var/lib/clickhouse
      - ./clickhouse/data_import:/var/lib/clickhouse/data_import  # Montar carpeta del dataset
    networks:
      - iceberg_net
    environment:
      - CLICKHOUSE_DB=default
      - CLICKHOUSE_USER=default
      - CLICKHOUSE_DO_NOT_CHOWN=1
      - CLICKHOUSE_PASSWORD=
```

**Paso 3:** Ejecuta el siguiente comando para iniciar los servicios:

```bash theme={null}
docker compose up
```

**Paso 4:** Espera a que todos los servicios estén listos. Puedes revisar los logs:

```bash theme={null}
docker-compose logs -f
```

<Note>
  La configuración del catálogo REST requiere que primero se carguen datos de ejemplo en las tablas Iceberg. Asegúrate de que el entorno de Spark haya creado y rellenado las tablas antes de intentar consultarlas desde ClickHouse. La disponibilidad de las tablas depende de la configuración específica de `docker-compose` y de los scripts de carga de datos de ejemplo.
</Note>

<div id="connecting-to-local-rest-catalog">
  ### Conectarse al REST Catalog local
</div>

Conéctese al contenedor de ClickHouse:

```bash theme={null}
docker exec -it clickhouse clickhouse-client
```

Luego, cree la conexión de base de datos al catálogo REST:

```sql theme={null}
SET allow_database_iceberg = 1;

CREATE DATABASE demo
ENGINE = DataLakeCatalog('http://rest:8181/v1', 'admin', 'password')
SETTINGS 
    catalog_type = 'rest', 
    storage_endpoint = 'http://minio:9000/lakehouse', 
    warehouse = 'demo'
```

<div id="querying-rest-catalog-tables-using-clickhouse">
  ## Consultar tablas del catálogo REST con ClickHouse
</div>

Ahora que la conexión está lista, puedes empezar a hacer consultas a través del catálogo REST. Por ejemplo:

```sql theme={null}
USE demo;

SHOW TABLES;
```

Si su configuración incluye datos de ejemplo (como el conjunto de datos de taxis), debería ver tablas como:

```response theme={null}
┌─name──────────┐
│ default.taxis │
└───────────────┘
```

<Note>
  Si no ves ninguna tabla, normalmente significa lo siguiente:

  1. El entorno de Spark aún no ha creado las tablas de ejemplo
  2. El servicio de catálogo REST todavía no se ha inicializado por completo
  3. El proceso de carga de los datos de ejemplo aún no ha finalizado

  Puedes revisar los logs de Spark para ver el progreso de creación de las tablas:

  ```bash theme={null}
  docker-compose logs spark
  ```
</Note>

Para consultar una tabla (si está disponible):

```sql theme={null}
SELECT count(*) FROM `default.taxis`;
```

```response theme={null}
┌─count()─┐
│ 2171187 │
└─────────┘
```

<Info>
  **Se requieren backticks**

  Los backticks son obligatorios porque ClickHouse no admite más de un espacio de nombres.
</Info>

Para inspeccionar el DDL de la tabla:

```sql theme={null}
SHOW CREATE TABLE `default.taxis`;
```

```response theme={null}
┌─statement─────────────────────────────────────────────────────────────────────────────────────┐
│ CREATE TABLE demo.`default.taxis`                                                             │
│ (                                                                                             │
│     `VendorID` Nullable(Int64),                                                               │
│     `tpep_pickup_datetime` Nullable(DateTime64(6)),                                           │
│     `tpep_dropoff_datetime` Nullable(DateTime64(6)),                                          │
│     `passenger_count` Nullable(Float64),                                                      │
│     `trip_distance` Nullable(Float64),                                                        │
│     `RatecodeID` Nullable(Float64),                                                           │
│     `store_and_fwd_flag` Nullable(String),                                                    │
│     `PULocationID` Nullable(Int64),                                                           │
│     `DOLocationID` Nullable(Int64),                                                           │
│     `payment_type` Nullable(Int64),                                                           │
│     `fare_amount` Nullable(Float64),                                                          │
│     `extra` Nullable(Float64),                                                                │
│     `mta_tax` Nullable(Float64),                                                              │
│     `tip_amount` Nullable(Float64),                                                           │
│     `tolls_amount` Nullable(Float64),                                                         │
│     `improvement_surcharge` Nullable(Float64),                                                │
│     `total_amount` Nullable(Float64),                                                         │
│     `congestion_surcharge` Nullable(Float64),                                                 │
│     `airport_fee` Nullable(Float64)                                                           │
│ )                                                                                             │
│ ENGINE = Iceberg('http://minio:9000/lakehouse/warehouse/default/taxis/', 'admin', '[HIDDEN]') │
└───────────────────────────────────────────────────────────────────────────────────────────────┘
```

<div id="loading-data-from-your-data-lake-into-clickhouse">
  ## Cargar datos desde tu lago de datos a ClickHouse
</div>

Si necesitas cargar datos desde el catálogo REST a ClickHouse, empieza por crear una tabla local en ClickHouse:

```sql theme={null}
CREATE TABLE taxis
(
    `VendorID` Int64,
    `tpep_pickup_datetime` DateTime64(6),
    `tpep_dropoff_datetime` DateTime64(6),
    `passenger_count` Float64,
    `trip_distance` Float64,
    `RatecodeID` Float64,
    `store_and_fwd_flag` String,
    `PULocationID` Int64,
    `DOLocationID` Int64,
    `payment_type` Int64,
    `fare_amount` Float64,
    `extra` Float64,
    `mta_tax` Float64,
    `tip_amount` Float64,
    `tolls_amount` Float64,
    `improvement_surcharge` Float64,
    `total_amount` Float64,
    `congestion_surcharge` Float64,
    `airport_fee` Float64
)
ENGINE = MergeTree()
PARTITION BY toYYYYMM(tpep_pickup_datetime)
ORDER BY (VendorID, tpep_pickup_datetime, PULocationID, DOLocationID);
```

A continuación, carga los datos desde la tabla de tu catálogo REST mediante un `INSERT INTO SELECT`:

```sql theme={null}
INSERT INTO taxis 
SELECT * FROM demo.`default.taxis`;
```