{"id":25935982,"url":"https://github.com/selimsevim/sfmc-ai-query-assistant","last_synced_at":"2026-05-13T02:02:44.387Z","repository":{"id":280371655,"uuid":"941771224","full_name":"selimsevim/sfmc-ai-query-assistant","owner":"selimsevim","description":"An AI-powered assistant that translates natural language into SQL queries for Salesforce Marketing Cloud (SFMC). Using GPT-4o, this tool understands user queries, maps them to relevant Data Extensions (DEs) and fields, and generates optimized SQL queries—making data retrieval in SFMC faster and easier.","archived":false,"fork":false,"pushed_at":"2025-03-03T03:17:30.000Z","size":0,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-03T03:29:15.919Z","etag":null,"topics":["gpt-4","marketing-automation","marketing-cloud","query","salesforce-marketing-cloud","sfmc","sql"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/selimsevim.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-03T02:47:11.000Z","updated_at":"2025-03-03T03:18:58.000Z","dependencies_parsed_at":"2025-03-03T03:39:21.914Z","dependency_job_id":null,"html_url":"https://github.com/selimsevim/sfmc-ai-query-assistant","commit_stats":null,"previous_names":["selimsevim/sfmc-ai-query-assistant"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/selimsevim%2Fsfmc-ai-query-assistant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/selimsevim%2Fsfmc-ai-query-assistant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/selimsevim%2Fsfmc-ai-query-assistant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/selimsevim%2Fsfmc-ai-query-assistant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/selimsevim","download_url":"https://codeload.github.com/selimsevim/sfmc-ai-query-assistant/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241768290,"owners_count":20017117,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gpt-4","marketing-automation","marketing-cloud","query","salesforce-marketing-cloud","sfmc","sql"],"created_at":"2025-03-04T01:39:55.750Z","updated_at":"2026-05-13T02:02:39.349Z","avatar_url":"https://github.com/selimsevim.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SFMC AI Query Assistant\n## Overview\n\nThe SFMC AI Query Assistant is a GPT-4o-powered tool designed to help Salesforce Marketing Cloud (SFMC) users easily generate optimized SQL queries from natural language inputs. By leveraging AI-driven intent recognition, it translates user-friendly queries into structured SQL statements, mapping relevant Data Extensions (DEs) and fields dynamically.\n\nThis tool eliminates the need for manual SQL writing, making data retrieval in SFMC faster, more accurate, and accessible to non-technical users. Additionally, it ensures SFMC SQL compliance, intelligently handling Data Views, enforcing valid joins, and preventing errors.\n\nThe assistant is expandable and can be enhanced with Data Extension management capabilities, allowing users to create, move, or delete DEs using simple commands. Whether you're a marketer, developer, or analyst, this AI-powered assistant helps streamline SFMC operations and improve efficiency.\n\n## Features\n\n✅ Natural Language to SQL – Enter a query like \"Show me all contacts who clicked X email last week\" and get the correct SQL.\n\n✅ Dynamic Data Extension \u0026 Field Lookup – Uses reference tables to map friendly terms to DE names and fields.\n\n✅ Strict SQL Compliance – Enforces SFMC SQL constraints (e.g., no WITH statements, correct JOINs, no unnecessary fields).\n\n✅ Data Views Handling – Automatically includes _job, _open, _click, and other SFMC Data Views when needed.\n\n✅ Error Handling \u0026 Query Validation – Ensures fields exist before generating queries to prevent errors.\n\n✅ Scalable for Future AI Integrations – Can be expanded to include Data Extension management, automation, and reporting.\n\n\n\n## How It Works\n\n1️⃣ User enters a query in natural language.\n\n2️⃣ GPT-4o extracts Data Extensions \u0026 fields from user input.\n\n3️⃣ The assistant fetches all available fields for those DEs.\n\n4️⃣ GPT-4o generates a fully structured SQL query based on the extracted data \u0026 relationships.\n\n5️⃣ The user receives the final SQL output in a CloudPage interface.\n\n\n## Example Queries \u0026 Outputs\n🔹 User Input: \"Find all contacts who clicked X email last week.\"\n\n🔹 Structured prompts:\n\n\n```\nYou are an AI that generates SQL queries for Salesforce Marketing Cloud (SFMC). Only generate the query, do not explain anything. Follow these strict rules:\n\n### **🔹 SQL Rules (Strict Adherence Required)**\n- **Allowed Clauses:** SELECT, JOIN, WHERE, GROUP BY, HAVING, ROW_NUMBER.\n- **Prohibited Clauses:** INSERT, UPDATE, DELETE, ORDER BY (unless inside `ROW_NUMBER() OVER (...)`), WITH.\n- **Allowed Joins:** INNER JOIN, LEFT JOIN (NO CROSS JOIN).\n- **Field Selection:** Do NOT use `*`. Always list fields explicitly.\n- **Data Extension Naming:** Use square brackets `[ ]` for DEs ALWAYS.\n- **Table Aliases:** Use aliases for readability, but keep full DE names in `FROM` and `JOIN`.\n- **Query Efficiency:** Always optimize queries for readability and performance.\n\n### **🔹 Data Views Handling Rules**\n- **SFMC Data Views such as `_job`, `_open`, `_click`, `_bounce`, etc., must be handled with proper joins.**\n- **If a user query involves opens, clicks, or sends, extract BOTH `_job` (Emails DE) AND the relevant event DE (`_open`, `_click`, etc.).**\n- **Always JOIN `_job` with event-based Data Views using `JobID` or `SubscriberKey`, based on available relationships.**\n- **Ensure that filters involving email sends, opens, clicks, or bounces use the correct event timestamps (e.g., `EventDate`).**\n.....\n```\n🔹 AI Output:\n\n```\nSELECT c.SubscriberKey, c.EventDate\nFROM _click c\nINNER JOIN _job j ON c.JobID = j.JobID\nWHERE c.EventDate \u003e= DATEADD(DAY, -7, GETDATE());\n```\n\n## Setup \u0026 Usage\n📌 Requirements: SFMC CloudPage, Configuration Data Extensions (References and Relationships), SSJS, GPT API Key.\n\n📌 Installation: Clone the repo, configure API keys, and deploy to your CloudPage.\n\n📌 Customization: Modify prompts \u0026 SQL rules to fit your business needs.\n\n📌 Necessary tables:\n\n1️⃣ de_references (Data Extension Reference Table)\n\nStores mappings of user-friendly terms to actual Data Extension (DE) names.\n\nde_references:\n| Column                                   | Type    | Length | Nullable | Primary Key |\n|------------------------------------------|---------|--------|----------|-------------|\n| `Reference`                   | Text  | 155     | ❌       | ✔          |\n| `DataExtensionName`                         | Text  | 155    | ❌       | ❌           |\n\n\n2️⃣ field_references (Field Reference Table)\n\nMaps user-friendly field names to actual fields within Data Extensions.\n\nfield_references:\n| Column                                   | Type    | Length | Nullable | Primary Key |\n|------------------------------------------|---------|--------|----------|-------------|\n| `Reference`                   | Text  | 155     | ❌       | ✔          |\n| `DataExtensionName`                         | Text  | 155    | ❌       | ❌           |\n| `FieldName`                  | Text  | 155    | ❌       | ❌           |\n\n\n3️⃣ relationships (Data Extension Relationships Table)\n\nDefines how Data Extensions are related (used for JOIN conditions in SQL queries).\n\nrelationships:\n| Column                                   | Type    | Length | Nullable | Primary Key |\n|------------------------------------------|---------|--------|----------|-------------|\n| `DE1`                   | Text  | 155     | ❌       | ✔          |\n| `DE2`                         | Text  | 155    | ❌       | ❌           |\n| `RelationshipField`                  | Text  | 155    | ❌       | ❌           |\n\n\n## Contribution\n\nContributions are welcome! Feel free to open an issue or submit a pull request if you find a bug or have an idea for improvement.\n\n## License\n\nThis project is licensed under the MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fselimsevim%2Fsfmc-ai-query-assistant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fselimsevim%2Fsfmc-ai-query-assistant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fselimsevim%2Fsfmc-ai-query-assistant/lists"}