{"id":3529,"library":"kylinpy","title":"Apache Kylin Python Client Library","description":"The `kylinpy` library provides a Python client to interact with Apache Kylin, an OLAP engine for Big Data, allowing users to query and manage Kylin instances programmatically. It abstracts the REST API interactions, facilitating tasks such as executing queries, managing projects, and retrieving metadata. The current version is 2.8.4, and it maintains an active release cadence, often aligning with Apache Kylin server updates.","status":"active","version":"2.8.4","language":"en","source_language":"en","source_url":"https://github.com/Kyligence/kylinpy","tags":["kylin","olap","big data","data warehousing","client","analytics"],"install":[{"cmd":"pip install kylinpy","lang":"bash","label":"Install kylinpy"}],"dependencies":[{"reason":"HTTP client for API communication.","package":"requests","optional":false},{"reason":"Used for converting query results into DataFrame objects via `query_to_dataframe`.","package":"pandas","optional":false},{"reason":"Standard dependency for Python package installation.","package":"setuptools","optional":false}],"imports":[{"symbol":"KylinClient","correct":"from kylinpy import KylinClient"},{"note":"Introduced in v2.8.0 for asyncio support. Use this for async operations.","symbol":"KylinAsyncClient","correct":"from kylinpy import KylinAsyncClient"}],"quickstart":{"code":"import os\nfrom kylinpy import KylinClient\n\n# Configure connection details using environment variables for security\nHOST = os.environ.get('KYLIN_HOST', 'localhost')\nPORT = os.environ.get('KYLIN_PORT', '7070')\nUSERNAME = os.environ.get('KYLIN_USERNAME', 'ADMIN')\nPASSWORD = os.environ.get('KYLIN_PASSWORD', 'KYLIN')\nPROJECT = os.environ.get('KYLIN_PROJECT', 'learn_kylin')\n\ntry:\n    # Initialize the KylinClient\n    client = KylinClient(\n        host=HOST,\n        port=PORT,\n        username=USERNAME,\n        password=PASSWORD\n    )\n\n    # Select the project context for operations\n    client.use_project(PROJECT)\n    print(f\"Connected to Kylin at {HOST}:{PORT}, project: {PROJECT}\")\n\n    # Execute a sample query and get results as a pandas DataFrame\n    sql_query = \"SELECT LSTG_FORMAT_NAME, sum(PRICE) FROM KYLIN_SALES GROUP BY LSTG_FORMAT_NAME ORDER BY sum(PRICE) DESC LIMIT 5\"\n    df = client.query_to_dataframe(sql_query)\n\n    print(\"\\nQuery Results (top 5 rows):\")\n    print(df.to_string())\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"Please ensure KYLIN_HOST, KYLIN_PORT, KYLIN_USERNAME, KYLIN_PASSWORD, and KYLIN_PROJECT environment variables are correctly set or provide valid defaults.\")","lang":"python","description":"This quickstart demonstrates how to connect to an Apache Kylin instance, select a project, and execute a simple SQL query using the `kylinpy` client. It retrieves the results directly into a pandas DataFrame. Credentials and project name are sourced from environment variables for secure and flexible configuration."},"warnings":[{"fix":"Always call `client.use_project()` with a valid project name before performing project-specific operations like querying or metadata retrieval.","message":"Many Kylin operations are scoped to a specific project. Forgetting to call `client.use_project(project_name)` after initializing `KylinClient` can lead to 'project not found' or authentication errors, even if your client credentials are correct.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Choose the appropriate query result method (`query_to_dataframe`, `query_to_list`, or lower-level API calls) based on your specific use case, performance requirements, and whether you intend to work with pandas DataFrames.","message":"While `kylinpy` offers `query_to_dataframe` for convenient integration with pandas, if pandas is not strictly needed or if you're dealing with very large result sets where DataFrame conversion overhead is a concern, consider using `client.query_to_list` or accessing raw API responses to manage memory and performance more directly.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For asynchronous operations, explicitly use `KylinAsyncClient` and adhere to `async`/`await` patterns. For synchronous applications, `KylinClient` remains the correct choice.","message":"As of `v2.8.0`, `kylinpy` introduced `KylinAsyncClient` for `asyncio` support. If you're building an asynchronous application, ensure you import `KylinAsyncClient` (e.g., `from kylinpy import KylinAsyncClient`) and use `await` with its methods. Mixing synchronous `KylinClient` methods with `asyncio` patterns without proper wrapping will lead to runtime errors.","severity":"gotcha","affected_versions":"v2.8.0+"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}