Metadata-Version: 2.1
Name: treinta_redshift
Version: 0.1.5
Summary: Libreria para data engineering
Author: cristian.pinela
Author-email: cristian.pinela@treinta.co
License: LICENSE
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: boto3 ==1.34.23
Requires-Dist: botocore ==1.34.23
Requires-Dist: numpy ==1.25.0
Requires-Dist: pandas ==2.0.2
Requires-Dist: pyarrow ==13.0.0

Para crear un `README.md` más extenso y detallado, que resalte las ventajas de tu librería y proporcione toda la información necesaria sobre las políticas de IAM requeridas, aquí tienes una versión ampliada y mejorada:

```markdown
# Treinta Redshift

`treinta_redshift` es una librería de Python diseñada específicamente para ingenieros de datos, analistas de Insights & Analytics y profesionales de Data Science que buscan una interacción simplificada con Amazon Redshift. Facilita una serie de operaciones críticas permitiendo a los usuarios centrarse en el análisis de datos sin tener que preocuparse por la complejidad subyacente de las operaciones de bases de datos.

## Ventajas Clave

- **Simplificación de Operaciones con Redshift**: Desde ejecutar consultas hasta manipular tablas, `treinta_redshift` convierte tareas complejas en operaciones sencillas y directas.
- **Integración Directa con Pandas**: La capacidad de transformar resultados de consultas en DataFrames de pandas y viceversa, facilita un flujo de trabajo analítico fluido, aprovechando la potencia de pandas para el análisis de datos.
- **Optimización de Cargas de Datos**: Utiliza el enfoque de Data Lake con S3 para una carga eficiente de datos a Redshift, manejando automáticamente la compresión y estructura de los archivos para optimizar tanto el almacenamiento como el rendimiento.
- **Flexibilidad**: Soporta operaciones a nivel de base de datos, esquema o tabla, y permite ajustes finos como limitar el número de entradas recuperadas, lo que ofrece a los usuarios control total sobre sus datos.


## Métodos en la librería
A continuación se listan los métodos que contiene la librería y su uso, además de su ejemplo:

### 1. `table_to_dataframe`

Este método permite a los usuarios consultar una tabla específica en Amazon Redshift y convertir los resultados de la consulta directamente en un DataFrame de pandas. Esto es especialmente útil para análisis de datos y manipulación de datos directamente en Python.

**Ejemplo:**

```python
df = table_to_dataframe(table='ventas', schema='public', database='mi_database', NUM_ENTRIES=100, cluster_identifier='mi-cluster-redshift', db_user='usuario_redshift')
```

Este código consulta las primeras 100 entradas de la tabla `ventas` en el esquema `public`, convirtiendo los resultados en un DataFrame para análisis posterior.

### 2. `query_to_dataframe`

Este método ejecuta cualquier consulta SQL personalizada en Amazon Redshift y devuelve los resultados como un DataFrame de pandas. Proporciona flexibilidad para realizar consultas complejas, incluyendo joins, subconsultas, y funciones de agregación.

**Ejemplo:**

```python
sql_query = "SELECT fecha, SUM(ventas) FROM public.ventas WHERE fecha > '2021-01-01' GROUP BY fecha;"
df = query_to_dataframe(sql_query=sql_query, cluster_identifier='mi-cluster-redshift', database='mi_database', db_user='usuario_redshift')
```

Aquí, se ejecuta una consulta para sumar las ventas por fecha después del 1 de enero de 2021, devolviendo un DataFrame con los resultados.

### 3. `dataframe_to_s3`

Este método facilita la exportación de un DataFrame de pandas a un archivo CSV comprimido en formato `.gz` y lo almacena en un bucket de S3. Es un paso preliminar importante antes de cargar datos en Redshift desde S3.

**Ejemplo:**

```python
df = pd.DataFrame({'columna1': [1, 2, 3], 'columna2': ['a', 'b', 'c']})
path_s3 = dataframe_to_s3(df=df, bucket="mi_bucket_s3", endpoint='mi_datalake', object_name='datos_ventas')
```

Este código guarda `df` como un archivo `.csv.gz` en `mi_bucket_s3` bajo el endpoint `mi_datalake` con un nombre de archivo generado automáticamente.

### 4. `load_s3_to_redshift`

Carga datos desde un archivo en S3 a una tabla específica en Redshift utilizando la instrucción COPY de Redshift para una carga eficiente. Este método es ideal para integrar grandes volúmenes de datos en Redshift para análisis avanzados.

**Ejemplo:**

```python
load_s3_to_redshift(table='ventas', schema='public', s3_object_path='s3://mi_bucket_s3/mi_datalake/mis_datos_ventas.csv.gz', database='mi_database', cluster_identifier='mi-cluster-redshift', db_user='usuario_redshift')
```

Este ejemplo carga datos desde un archivo `mis_datos_ventas.csv.gz` en S3 a la tabla `ventas` en Redshift.

### 5. `dataframe_to_redshift`

Combina `dataframe_to_s3` y `load_s3_to_redshift` en un solo paso, simplificando el proceso de cargar datos desde un DataFrame de pandas directamente a una tabla en Redshift. Este método es especialmente valioso para flujos de trabajo de análisis de datos que requieren la actualización frecuente de datos en Redshift.

**Ejemplo:**

```python
df = pd.DataFrame({'columna1': [1, 2, 3], 'columna2': ['a', 'b', 'c']})
dataframe_to_redshift(df=df, table='ventas', schema='public', database='mi_database', db_user='usuario_redshift', cluster_identifier='mi-cluster-redshift')
```

Aquí, `df` se carga directamente a la tabla `ventas` en Redshift, facilitando un flujo de trabajo de análisis de datos eficiente y automatizado.

Cada uno de estos métodos ofrece una funcionalidad específica que contribuye a un ecosistema de análisis de datos robusto y flexible, permitiendo a los usuarios de `treinta_redshift` manipular y analizar datos en Redshift de manera eficiente y efectiva.

## Requisitos Previos

Para utilizar `treinta_redshift`, asegúrate de cumplir con los siguientes requisitos:

- **Python 3.11** o superior.
- **Acceso configurado a AWS**: Un rol de AWS IAM con los permisos adecuados para interactuar con Redshift y S3.

### Políticas de IAM Requeridas

El rol de IAM debe incluir políticas que permitan las siguientes acciones:

- Acciones de Redshift para ejecutar consultas y manipular datos.
- Acciones de S3 para almacenar y recuperar datos.

A continuación, se proporcionan las políticas de ejemplo que debes adjuntar a tu rol de IAM:

```json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "redshift:GetClusterCredentials",
            "Resource": "arn:aws:redshift:region:account-id:dbname:database-name/dbuser:database-user"
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:GetObject",
                "s3:DeleteObject",
                "s3:ListBucket"
            ],
            "Resource": [
                "arn:aws:s3:::redshift_python_datalake/*",
                "arn:aws:s3:::redshift_python_datalake"
            ]
        }
    ]
}
```

Adapta las ARNs según tu región, ID de cuenta, nombre de base de datos, usuario de base de datos y nombre de bucket de S3.

## Instalación

```bash
pip install treinta_redshift
```

## Uso

### Escribir DataFrame en Redshift

`treinta_redshift` automatiza y simplifica la carga de DataFrames a Redshift, utilizando internamente un Data Lake en S3 para una transferencia eficiente.

```python
from treinta_redshift import dataframe_to_redshift

# Suponiendo que 'df' es tu DataFrame de pandas
dataframe_to_redshift(df, 'nombre_tabla', 'esquema', database='tu-database', db_user='tu-usuario', cluster_identifier='tu-cluster')
```

### Consultar Datos y Convertir en DataFrame

```python
from treinta_redshift import query_to_dataframe

sql_query = "SELECT * FROM esquema.tabla LIMIT 10;"
df = query_to_dataframe(sql_query, cluster_identifier='tu-cluster', database='tu-database', db_user='tu-usuario')
```

## Licencia

Este proyecto está bajo la Licencia MIT. Consulta el archivo `LICENSE` para más detalles.

## Contacto

Para soporte, preguntas o colaboraciones, por favor, abre un issue en el [repositorio de GitHub](#) para que podamos seguir la conversación.

```

Este `README.md` proporciona una introducción completa a la librería, destacando sus beneficios y proporcionando toda la información necesaria para que los usuarios la instalen, configuren y comiencen a usarla eficazmente.
