treinta-redshift 0.1.5

Libreria para data engineering

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:

# 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:

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:

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:

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:

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:

{
    "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

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.

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

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.