{"id":4248,"library":"scim2-filter-parser","title":"SCIM2 Filter Parser","description":"scim2-filter-parser (SFP) is a customizable Python library designed to parse and transpile SCIM 2.0 filter queries. It breaks down SCIM queries into tokens, constructs an Abstract Syntax Tree (AST), and can then convert this AST into other query languages, such as SQL WHERE clauses or Django Q objects. The library is currently at version 0.7.0 and is actively maintained.","status":"active","version":"0.7.0","language":"en","source_language":"en","source_url":"https://github.com/15five/scim2-filter-parser","tags":["SCIM","SCIM2","filter","parser","transpiler","SQL","Django","API"],"install":[{"cmd":"pip install scim2-filter-parser","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"Primary class for transpiling SCIM filters to SQL.","symbol":"SQLQuery","correct":"from scim2_filter_parser.queries import SQLQuery"},{"note":"Function to transpile SCIM filters into Django Q objects.","symbol":"get_query","correct":"from scim2_filter_parser.transpilers.django_q_object import get_query"}],"quickstart":{"code":"from scim2_filter_parser.queries import SQLQuery\n\n# Define a mapping from SCIM attributes to your database column names.\n# This is crucial for the parser to generate correct SQL.\nattribute_map = {\n    'userName': 'users.username',\n    'emails.value': 'emails.email_address',\n    'emails.type': 'emails.type',\n    'name.familyName': 'users.last_name',\n    'name.givenName': 'users.first_name'\n}\n\n# Define necessary SQL JOINs if your SCIM attributes span multiple tables.\njoins = [\n    'LEFT JOIN emails ON emails.user_id = users.id'\n]\n\nscim_filter = 'userName eq \"bjensen\" or emails[type eq \"work\" and value co \"@example.com\"]'\n\ntry:\n    # Instantiate the SQLQuery parser\n    query_builder = SQLQuery(\n        scim_filter=scim_filter,\n        attribute_map=attribute_map,\n        joins=joins\n    )\n\n    # Get the generated SQL WHERE clause and parameters\n    sql_where_clause = query_builder.sql\n    query_parameters = query_builder.params\n\n    print(f\"Generated SQL WHERE clause: {sql_where_clause}\")\n    print(f\"Query parameters: {query_parameters}\")\n\n    # Example of how you might use it (DO NOT run this directly without proper DB connection and sanitization):\n    # import sqlite3\n    # conn = sqlite3.connect(':memory:')\n    # cursor = conn.cursor()\n    # # For demonstration, imagine 'users' and 'emails' tables exist\n    # # cursor.execute(f\"SELECT * FROM users {joins[0]} WHERE {sql_where_clause}\", query_parameters)\n    # # results = cursor.fetchall()\n    # # print(f\"Query results: {results}\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")","lang":"python","description":"This quickstart demonstrates how to use `scim2-filter-parser` to convert a SCIM filter string into a SQL WHERE clause and corresponding parameters. It highlights the use of `SQLQuery`, an `attribute_map` to link SCIM attributes to database columns, and optional `joins` for complex queries. The output provides a parameterized query suitable for execution with database connectors, emphasizing safe practices against SQL injection."},"warnings":[{"fix":"Always use the `SQLQuery.sql` output as the query string and `SQLQuery.params` as the separate sequence of parameters when executing with a database driver (e.g., `cursor.execute(sql_query, query_parameters)`).","message":"When using the raw SQL output (e.g., from the command-line tool or if you concatenate `sql_where_clause` directly without `query_parameters`), there is a significant risk of SQL injection. The library provides `params` separately for safe parameterized query execution.","severity":"breaking","affected_versions":"All versions"},{"fix":"Thoroughly review and test your `attribute_map` configuration to ensure SCIM attributes correctly map to your database tables and columns, including handling of complex attributes and multi-valued attributes.","message":"The `attribute_map` is highly specific to your database schema and must be carefully configured. Incorrect mappings will lead to invalid SQL queries or unexpected filtering behavior.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For databases requiring different parameter placeholders, subclass `SQLQuery`:\n`class CustomSQLQuery(SQLQuery):\n    placeholder = '?' # Or other required placeholder`","message":"By default, `SQLQuery` uses `%s` as the placeholder for query parameters, which is common in PostgreSQL. If your database (e.g., SQLite, MySQL with `?` or named parameters) requires a different placeholder, you must subclass `SQLQuery` and override the `placeholder` class variable.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For Django integration, import `from scim2_filter_parser.transpilers.django_q_object import get_query` and consult the GitHub README for usage examples with Django Q objects.","message":"The library primarily demonstrates SQL output. If you intend to use it with Django models, you need to import and use `scim2_filter_parser.transpilers.django_q_object.get_query` to generate Django Q objects, which has a different API.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}