{"id":7401,"library":"mdxpy","title":"mdxpy","description":"mdxpy is a Python library designed to simplify the programmatic creation of MDX (Multidimensional Expressions) queries for IBM Planning Analytics (TM1). It eliminates the need for manual string concatenation, reduces syntax errors, and makes MDX generation more robust and easier to refactor. The library is currently at version 1.3.2 and maintains an active release cadence with regular updates.","status":"active","version":"1.3.2","language":"en","source_language":"en","source_url":"https://github.com/cubewise-code/mdxpy","tags":["MDX","TM1","OLAP","analytics","data warehousing","business intelligence"],"install":[{"cmd":"pip install mdxpy","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Highly recommended for interacting with TM1 servers, as mdxpy often generates MDX for TM1py's `execute_mdx_dataframe` functions.","package":"TM1py","optional":true}],"imports":[{"symbol":"MdxBuilder","correct":"from mdxpy import MdxBuilder"},{"symbol":"MdxHierarchySet","correct":"from mdxpy import MdxHierarchySet"},{"symbol":"Member","correct":"from mdxpy import Member"},{"symbol":"DimensionProperty","correct":"from mdxpy import DimensionProperty"},{"symbol":"MdxTuple","correct":"from mdxpy import MdxTuple"}],"quickstart":{"code":"import os\nfrom TM1py import TM1Service\nfrom mdxpy import MdxBuilder, MdxHierarchySet, DimensionProperty\n\n# TM1 connection details from environment variables for security\nTM1_ADDRESS = os.environ.get('TM1_ADDRESS', 'localhost')\nTM1_PORT = int(os.environ.get('TM1_PORT', 12354))\nTM1_SSL = os.environ.get('TM1_SSL', 'True').lower() == 'true'\nTM1_USER = os.environ.get('TM1_USER', 'admin')\nTM1_PASSWORD = os.environ.get('TM1_PASSWORD', 'apple')\n\n# This example assumes TM1py is installed and TM1 server is accessible\ntry:\n    with TM1Service(\n        address=TM1_ADDRESS,\n        port=TM1_PORT,\n        ssl=TM1_SSL,\n        user=TM1_USER,\n        password=TM1_PASSWORD\n    ) as tm1:\n        query = MdxBuilder.from_cube(\"SalesCube\")\n        query.add_hierarchy_set_to_row_axis(\n            MdxHierarchySet.all_leaves(\"Account\", \"Account\")\n        )\n        query.add_properties_to_row_axis(\n            DimensionProperty.of(\"Account\", \"Description\"),\n            DimensionProperty.of(\"Account\", \"Type\")\n        )\n        query.add_hierarchy_set_to_column_axis(\n            MdxHierarchySet.all_leaves(\"Time\", \"Time\")\n        )\n\n        mdx_query = query.to_mdx()\n        print(\"Generated MDX Query:\")\n        print(mdx_query)\n\n        # Execute the MDX query using TM1py (optional, for full example)\n        # df = tm1.execute_mdx_dataframe(mdx_query)\n        # print(\"\\nQuery Results (first 5 rows if TM1py executed):\")\n        # print(df.head())\n\nexcept ImportError:\n    print(\"TM1py not installed. Install with 'pip install TM1py' to run full example.\")\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")","lang":"python","description":"This quickstart demonstrates building a basic MDX query for a 'SalesCube' cube, retrieving all leaf members from 'Account' and 'Time' dimensions, including properties for 'Account'. It uses `TM1Service` from `TM1py` to illustrate a common integration pattern."},"warnings":[{"fix":"Review and update object names in your MDXpy code to use lower case where applicable. Test thoroughly after upgrading.","message":"In version 0.4, object names were standardized to lower case. This may cause issues for applications built with earlier versions that relied on specific casing.","severity":"breaking","affected_versions":"<0.4 to 0.4+"},{"fix":"Migrate usage of `MdxSet` to the new `MdxHierarchySet` or other dedicated classes based on your query requirements. Consult the documentation for the specific methods.","message":"Version 0.4 introduced a significant refactoring that broke `MdxHierarchySet` and `MdxSet` into two distinct classes. Code using `MdxSet` functionality might need to be rewritten to use `MdxHierarchySet` or other appropriate classes.","severity":"breaking","affected_versions":"<0.4 to 0.4+"},{"fix":"Ensure your code uses the correct method for combining sets based on your installed `mdxpy` version. For `1.1+`, `unions` is available. For versions where it was absent, alternatives like `union_of_sets` might have been used.","message":"The `unions` function on `MdxHierarchySet` was re-introduced in version 1.1. If you previously upgraded from a very old version to one where it was removed, and then upgrade to 1.1+, you might re-encounter this function.","severity":"gotcha","affected_versions":"Affected if upgrading from pre-1.1 versions where 'unions' was unavailable to 1.1+"},{"fix":"Adopt the `add_properties_to_row_axis` or `add_properties_to_column_axis` methods with `DimensionProperty.of()` for explicit property inclusion, as demonstrated in the quickstart.","message":"Version 1.0 introduced the ability to add dimension properties per axis. This enhanced functionality might require updates to existing MDX generation logic if you were previously handling properties differently.","severity":"gotcha","affected_versions":"<1.0 to 1.0+"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install `TM1py` using `pip install TM1py` and ensure `from TM1py import TM1Service` is present in your code.","cause":"The `TM1py` library, commonly used with `mdxpy` for actual TM1 server interaction, is not installed or not imported.","error":"NameError: name 'TM1Service' is not defined"},{"fix":"Upgrade to `mdxpy>=1.1` where the `unions` function was re-introduced, or use alternative methods for combining sets available in your specific `mdxpy` version.","cause":"This error occurs when using an `mdxpy` version (e.g., between 0.4 and 1.1) where the `unions` function was temporarily removed from `MdxHierarchySet`.","error":"AttributeError: 'MdxHierarchySet' object has no attribute 'unions'"},{"fix":"Ensure you construct `MdxHierarchySet` objects using their static methods, such as `MdxHierarchySet.all_leaves(\"Dimension\", \"Hierarchy\")` or `MdxHierarchySet.tm1_subset_to_set(\"Dimension\", \"Hierarchy\", \"Subset\")`, before passing them to the builder.","cause":"An `mdxpy` builder function (e.g., `add_hierarchy_set_to_row_axis`) expects an `MdxHierarchySet` object, but a raw string was provided instead.","error":"TypeError: 'str' object cannot be interpreted as an MdxHierarchySet"},{"fix":"Leverage `mdxpy`'s programmatic builder pattern (`MdxBuilder`, `Member`, `MdxHierarchySet`, etc.) to construct the MDX query. This significantly reduces the likelihood of syntax errors.","cause":"Attempting to manually concatenate MDX strings, which is prone to syntax errors (e.g., missing brackets, incorrect commas), a problem `mdxpy` is designed to solve.","error":"MDX query not valid: Syntax error at or near '...'"}]}