MindsDB 25.7.2.0__py3-none-any.whl → 25.7.4.0__py3-none-any.whl

mindsdb/integrations/handlers/s3_handler/s3_handler.py

@@ -7,6 +7,7 @@ from duckdb import HTTPException
 from mindsdb_sql_parser import parse_sql
 import pandas as pd
 from typing import Text, Dict, Optional
+from botocore.client import Config
 from botocore.exceptions import ClientError
 
 from mindsdb_sql_parser.ast.base import ASTNode
@@ -16,7 +17,7 @@ from mindsdb.utilities import log
 from mindsdb.integrations.libs.response import (
     HandlerStatusResponse as StatusResponse,
     HandlerResponse as Response,
-    RESPONSE_TYPE
+    RESPONSE_TYPE,
 )
 
 from mindsdb.integrations.libs.api_handler import APIResource, APIHandler
@@ -26,16 +27,12 @@ logger = log.getLogger(__name__)
 
 
 class ListFilesTable(APIResource):
-
-    def list(self,
-             targets: List[str] = None,
-             conditions: List[FilterCondition] = None,
-             limit: int = None,
-             *args, **kwargs) -> pd.DataFrame:
-
+    def list(
+        self, targets: List[str] = None, conditions: List[FilterCondition] = None, limit: int = None, *args, **kwargs
+    ) -> pd.DataFrame:
         buckets = None
         for condition in conditions:
-            if condition.column == 'bucket':
+            if condition.column == "bucket":
                 if condition.op == FilterOperator.IN:
                     buckets = condition.value
                 elif condition.op == FilterOperator.EQUAL:
@@ -44,25 +41,27 @@ class ListFilesTable(APIResource):
 
         data = []
         for obj in self.handler.get_objects(limit=limit, buckets=buckets):
-            path = obj['Key']
-            path = path.replace('`', '')
+            path = obj["Key"]
+            path = path.replace("`", "")
             item = {
-                'path': path,
-                'bucket': obj['Bucket'],
-                'name': path[path.rfind('/') + 1:],
-                'extension': path[path.rfind('.') + 1:]
+                "path": path,
+                "bucket": obj["Bucket"],
+                "name": path[path.rfind("/") + 1 :],
+                "extension": path[path.rfind(".") + 1 :],
             }
 
+            if targets and "public_url" in targets:
+                item["public_url"] = self.handler.generate_sas_url(path, obj["Bucket"])
+
             data.append(item)
 
         return pd.DataFrame(data=data, columns=self.get_columns())
 
     def get_columns(self) -> List[str]:
-        return ["path", "name", "extension", "bucket", "content"]
+        return ["path", "name", "extension", "bucket", "content", "public_url"]
 
 
 class FileTable(APIResource):
-
     def list(self, targets: List[str] = None, table_name=None, *args, **kwargs) -> pd.DataFrame:
         return self.handler.read_as_table(table_name)
 
@@ -76,9 +75,9 @@ class S3Handler(APIHandler):
     This handler handles connection and execution of the SQL statements on AWS S3.
     """
 
-    name = 's3'
+    name = "s3"
     # TODO: Can other file formats be supported?
-    supported_file_formats = ['csv', 'tsv', 'json', 'parquet']
+    supported_file_formats = ["csv", "tsv", "json", "parquet"]
 
     def __init__(self, name: Text, connection_data: Optional[Dict], **kwargs):
         """
@@ -96,7 +95,7 @@ class S3Handler(APIHandler):
         self.connection = None
         self.is_connected = False
         self.thread_safe = True
-        self.bucket = self.connection_data.get('bucket')
+        self.bucket = self.connection_data.get("bucket")
         self._regions = {}
 
         self._files_table = ListFilesTable(self)
@@ -119,8 +118,8 @@ class S3Handler(APIHandler):
             return self.connection
 
         # Validate mandatory parameters.
-        if not all(key in self.connection_data for key in ['aws_access_key_id', 'aws_secret_access_key']):
-            raise ValueError('Required parameters (aws_access_key_id, aws_secret_access_key) must be provided.')
+        if not all(key in self.connection_data for key in ["aws_access_key_id", "aws_secret_access_key"]):
+            raise ValueError("Required parameters (aws_access_key_id, aws_secret_access_key) must be provided.")
 
         # Connect to S3 and configure mandatory credentials.
         self.connection = self._connect_boto3()
@@ -152,13 +151,13 @@ class S3Handler(APIHandler):
         duckdb_conn.execute(f"SET s3_secret_access_key='{self.connection_data['aws_secret_access_key']}'")
 
         # Configure optional parameters.
-        if 'aws_session_token' in self.connection_data:
+        if "aws_session_token" in self.connection_data:
             duckdb_conn.execute(f"SET s3_session_token='{self.connection_data['aws_session_token']}'")
 
         # detect region for bucket
         if bucket not in self._regions:
             client = self.connect()
-            self._regions[bucket] = client.get_bucket_location(Bucket=bucket)['LocationConstraint']
+            self._regions[bucket] = client.get_bucket_location(Bucket=bucket)["LocationConstraint"]
 
         region = self._regions[bucket]
         duckdb_conn.execute(f"SET s3_region='{region}'")
@@ -177,15 +176,17 @@ class S3Handler(APIHandler):
         """
         # Configure mandatory credentials.
         config = {
-            'aws_access_key_id': self.connection_data['aws_access_key_id'],
-            'aws_secret_access_key': self.connection_data['aws_secret_access_key']
+            "aws_access_key_id": self.connection_data["aws_access_key_id"],
+            "aws_secret_access_key": self.connection_data["aws_secret_access_key"],
         }
 
         # Configure optional parameters.
-        if 'aws_session_token' in self.connection_data:
-            config['aws_session_token'] = self.connection_data['aws_session_token']
+        optional_parameters = ["region_name", "aws_session_token"]
+        for parameter in optional_parameters:
+            if parameter in self.connection_data:
+                config[parameter] = self.connection_data[parameter]
 
-        client = boto3.client('s3', **config)
+        client = boto3.client("s3", **config, config=Config(signature_version="s3v4"))
 
         # check connection
         if self.bucket is not None:
@@ -219,7 +220,7 @@ class S3Handler(APIHandler):
             self._connect_boto3()
             response.success = True
         except (ClientError, ValueError) as e:
-            logger.error(f'Error connecting to S3 with the given credentials, {e}!')
+            logger.error(f"Error connecting to S3 with the given credentials, {e}!")
             response.error_message = str(e)
 
         if response.success and need_to_close:
@@ -235,8 +236,8 @@ class S3Handler(APIHandler):
             return self.bucket, key
 
         # get bucket from first part of the key
-        ar = key.split('/')
-        return ar[0], '/'.join(ar[1:])
+        ar = key.split("/")
+        return ar[0], "/".join(ar[1:])
 
     def read_as_table(self, key) -> pd.DataFrame:
         """
@@ -245,7 +246,6 @@ class S3Handler(APIHandler):
         bucket, key = self._get_bucket(key)
 
         with self._connect_duckdb(bucket) as connection:
-
             cursor = connection.execute(f"SELECT * FROM 's3://{bucket}/{key}'")
 
             return cursor.fetchdf()
@@ -259,7 +259,7 @@ class S3Handler(APIHandler):
         client = self.connect()
 
         obj = client.get_object(Bucket=bucket, Key=key)
-        content = obj['Body'].read()
+        content = obj["Body"].read()
         return content
 
     def add_data_to_table(self, key, df) -> None:
@@ -277,7 +277,7 @@ class S3Handler(APIHandler):
             client = self.connect()
             client.head_object(Bucket=bucket, Key=key)
         except ClientError as e:
-            logger.error(f'Error querying the file {key} in the bucket {bucket}, {e}!')
+            logger.error(f"Error querying the file {key} in the bucket {bucket}, {e}!")
             raise e
 
         with self._connect_duckdb(bucket) as connection:
@@ -309,31 +309,28 @@ class S3Handler(APIHandler):
         if isinstance(query, Select):
             table_name = query.from_table.parts[-1]
 
-            if table_name == 'files':
+            if table_name == "files":
                 table = self._files_table
                 df = table.select(query)
 
                 # add content
                 has_content = False
                 for target in query.targets:
-                    if isinstance(target, Identifier) and target.parts[-1].lower() == 'content':
+                    if isinstance(target, Identifier) and target.parts[-1].lower() == "content":
                         has_content = True
                         break
                 if has_content:
-                    df['content'] = df['path'].apply(self._read_as_content)
+                    df["content"] = df["path"].apply(self._read_as_content)
             else:
-                extension = table_name.split('.')[-1]
+                extension = table_name.split(".")[-1]
                 if extension not in self.supported_file_formats:
-                    logger.error(f'The file format {extension} is not supported!')
-                    raise ValueError(f'The file format {extension} is not supported!')
+                    logger.error(f"The file format {extension} is not supported!")
+                    raise ValueError(f"The file format {extension} is not supported!")
 
                 table = FileTable(self, table_name=table_name)
                 df = table.select(query)
 
-            response = Response(
-                RESPONSE_TYPE.TABLE,
-                data_frame=df
-            )
+            response = Response(RESPONSE_TYPE.TABLE, data_frame=df)
         elif isinstance(query, Insert):
             table_name = query.table.parts[-1]
             table = FileTable(self, table_name=table_name)
@@ -364,7 +361,7 @@ class S3Handler(APIHandler):
             scan_buckets = [self.bucket]
         else:
             add_bucket_to_name = True
-            scan_buckets = [b['Name'] for b in client.list_buckets()['Buckets']]
+            scan_buckets = [b["Name"] for b in client.list_buckets()["Buckets"]]
 
         objects = []
         for bucket in scan_buckets:
@@ -372,23 +369,38 @@ class S3Handler(APIHandler):
                 continue
 
             resp = client.list_objects_v2(Bucket=bucket)
-            if 'Contents' not in resp:
+            if "Contents" not in resp:
                 continue
 
-            for obj in resp['Contents']:
-                if obj.get('StorageClass', 'STANDARD') != 'STANDARD':
+            for obj in resp["Contents"]:
+                if obj.get("StorageClass", "STANDARD") != "STANDARD":
                     continue
 
-                obj['Bucket'] = bucket
+                obj["Bucket"] = bucket
                 if add_bucket_to_name:
                     # bucket is part of the name
-                    obj['Key'] = f'{bucket}/{obj["Key"]}'
+                    obj["Key"] = f"{bucket}/{obj['Key']}"
                 objects.append(obj)
             if limit is not None and len(objects) >= limit:
                 break
 
         return objects
 
+    def generate_sas_url(self, key: str, bucket: str) -> str:
+        """
+        Generates a pre-signed URL for accessing an object in the S3 bucket.
+
+        Args:
+            key (str): The key (path) of the object in the S3 bucket.
+            bucket (str): The name of the S3 bucket.
+
+        Returns:
+            str: The pre-signed URL for accessing the object.
+        """
+        client = self.connect()
+        url = client.generate_presigned_url("get_object", Params={"Bucket": bucket, "Key": key}, ExpiresIn=3600)
+        return url
+
     def get_tables(self) -> Response:
         """
         Retrieves a list of tables (objects) in the S3 bucket.
@@ -402,21 +414,13 @@ class S3Handler(APIHandler):
         # Get only the supported file formats.
         # Wrap the object names with backticks to prevent SQL syntax errors.
         supported_names = [
-            f"`{obj['Key']}`"
-            for obj in self.get_objects()
-            if obj['Key'].split('.')[-1] in self.supported_file_formats
+            f"`{obj['Key']}`" for obj in self.get_objects() if obj["Key"].split(".")[-1] in self.supported_file_formats
         ]
 
         # virtual table with list of files
-        supported_names.insert(0, 'files')
+        supported_names.insert(0, "files")
 
-        response = Response(
-            RESPONSE_TYPE.TABLE,
-            data_frame=pd.DataFrame(
-                supported_names,
-                columns=['table_name']
-            )
-        )
+        response = Response(RESPONSE_TYPE.TABLE, data_frame=pd.DataFrame(supported_names, columns=["table_name"]))
 
         return response
 
@@ -433,11 +437,7 @@ class S3Handler(APIHandler):
         Returns:
             Response: A response object containing the column details, formatted as per the `Response` class.
         """
-        query = Select(
-            targets=[Star()],
-            from_table=Identifier(parts=[table_name]),
-            limit=Constant(1)
-        )
+        query = Select(targets=[Star()], from_table=Identifier(parts=[table_name]), limit=Constant(1))
 
         result = self.query(query)
 
@@ -445,10 +445,12 @@ class S3Handler(APIHandler):
             RESPONSE_TYPE.TABLE,
             data_frame=pd.DataFrame(
                 {
-                    'column_name': result.data_frame.columns,
-                    'data_type': [data_type if data_type != 'object' else 'string' for data_type in result.data_frame.dtypes]
+                    "column_name": result.data_frame.columns,
+                    "data_type": [
+                        data_type if data_type != "object" else "string" for data_type in result.data_frame.dtypes
+                    ],
                 }
-            )
+            ),
         )
 
         return response

mindsdb/integrations/handlers/salesforce_handler/constants.py

@@ -0,0 +1,208 @@
+"""
+Constants for Salesforce handler.
+"""
+
+
+def get_soql_instructions(integration_name):
+    return f"""This handler executes SOQL (Salesforce Object Query Language), NOT SQL! Follow these rules strictly:
+
+**BASIC STRUCTURE:**
+- NO "SELECT *" - must explicitly list all fields
+  SQL: SELECT * FROM Account;
+  SOQL: SELECT Id, Name, Industry FROM Account
+- NO table aliases - use full table names only
+  SQL: SELECT a.Name FROM Account a;
+  SOQL: SELECT Name FROM Account
+- NO column aliases - field names cannot be aliased
+  SQL: SELECT Name AS CompanyName FROM Account;
+  SOQL: SELECT Name FROM Account
+- NO DISTINCT keyword - not supported in SOQL
+  SQL: SELECT DISTINCT Industry FROM Account;
+  SOQL: Not possible - use separate logic
+- NO subqueries in FROM clause - only relationship-based subqueries allowed
+  SQL: SELECT * FROM (SELECT Name FROM Account) AS AccountNames;
+  SOQL: Not supported
+
+**FIELD SELECTION:**
+- Always include Id field when querying
+  CORRECT: SELECT Id, Name, Industry FROM Account
+  INCORRECT: SELECT Name, Industry FROM Account
+- Field names are case-sensitive
+  CORRECT: SELECT CreatedDate FROM Account
+  INCORRECT: SELECT createddate FROM Account
+- Use exact field names from the data catalog
+  CORRECT: SELECT CustomerPriority__c FROM Account
+  INCORRECT: SELECT customer_priority FROM Account
+
+**FILTERING (WHERE clause):**
+- Date/DateTime fields: Use unquoted literals in YYYY-MM-DD or YYYY-MM-DDThh:mm:ssZ format
+  CORRECT: WHERE CloseDate >= 2025-05-28
+  CORRECT: WHERE CreatedDate >= 2025-05-28T10:30:00Z
+  INCORRECT: WHERE CloseDate >= '2025-05-28'
+  INCORRECT: WHERE CreatedDate >= "2025-05-28"
+- Special date literals: TODAY, YESTERDAY, LAST_WEEK, LAST_MONTH, LAST_QUARTER, LAST_YEAR, THIS_WEEK, THIS_MONTH, THIS_QUARTER, THIS_YEAR
+  CORRECT: WHERE CreatedDate = TODAY
+  CORRECT: WHERE LastModifiedDate >= LAST_MONTH
+  CORRECT: WHERE CloseDate = THIS_QUARTER
+- LIKE operator: Only supports % wildcard, NO underscore (_) wildcard
+  CORRECT: WHERE Name LIKE '%Corp%'
+  CORRECT: WHERE Name LIKE 'Acme%'
+  INCORRECT: WHERE Name LIKE 'A_me%'
+- BETWEEN operator: NOT supported, use >= AND <= instead
+  SQL: WHERE CreatedDate BETWEEN '2025-01-01' AND '2025-12-31'
+  SOQL: WHERE CreatedDate >= 2025-01-01 AND CreatedDate <= 2025-12-31
+- Boolean values: Use lowercase true/false, NOT TRUE/FALSE
+  CORRECT: WHERE Active__c = true
+  CORRECT: WHERE IsDeleted = false
+  INCORRECT: WHERE Active__c = TRUE
+  INCORRECT: WHERE IsDeleted = FALSE
+- NULL values: Use lowercase null, NOT NULL
+  CORRECT: WHERE ParentId = null
+  CORRECT: WHERE Description != null
+  INCORRECT: WHERE ParentId IS NULL
+  INCORRECT: WHERE Description IS NOT NULL
+- String values: Use single quotes for strings
+  CORRECT: WHERE Industry = 'Technology'
+  CORRECT: WHERE Name = 'Acme Corp'
+  INCORRECT: WHERE Industry = "Technology"
+- Multi-select picklist fields: Use INCLUDES('value1;value2') or EXCLUDES('value1;value2')
+  CORRECT: WHERE Services__c INCLUDES ('Consulting;Support')
+  CORRECT: WHERE Services__c EXCLUDES ('Training')
+  INCORRECT: WHERE Services__c = 'Consulting'
+
+**JOINS:**
+- NO explicit JOIN syntax supported
+  SQL: SELECT a.Name, c.FirstName FROM Account a JOIN Contact c ON a.Id = c.AccountId
+  SOQL: Not supported - use relationship traversal (not applicable in this use case)
+
+**AGGREGATES:**
+- NO COUNT(*) - use COUNT(Id) instead
+  SQL: SELECT COUNT(*) FROM Account
+  SOQL: SELECT COUNT(Id) FROM Account
+- Cannot mix aggregate functions with non-aggregate fields unless using GROUP BY
+  CORRECT: SELECT Industry, COUNT(Id) FROM Account GROUP BY Industry
+  CORRECT: SELECT COUNT(Id) FROM Account
+  INCORRECT: SELECT Industry, Name, COUNT(Id) FROM Account
+- NO GROUP_CONCAT or string aggregation functions
+  SQL: SELECT GROUP_CONCAT(Name) FROM Account
+  SOQL: Not supported
+- NO HAVING clause
+  SQL: SELECT Industry, COUNT(*) FROM Account GROUP BY Industry HAVING COUNT(*) > 5
+  SOQL: Not supported - filter with separate logic
+- GROUP BY has limited field type support
+  CORRECT: SELECT Industry, COUNT(Id) FROM Account GROUP BY Industry
+  INCORRECT: SELECT Description, COUNT(Id) FROM Account GROUP BY Description (textarea fields not supported)
+
+**FUNCTIONS:**
+- Date functions: CALENDAR_MONTH(), CALENDAR_YEAR(), CALENDAR_QUARTER(), DAY_IN_MONTH(), DAY_IN_WEEK(), DAY_IN_YEAR(), HOUR_IN_DAY(), WEEK_IN_MONTH(), WEEK_IN_YEAR()
+  CORRECT: SELECT Id, Name FROM Account WHERE CALENDAR_YEAR(CreatedDate) = 2025
+  CORRECT: SELECT Id, Name FROM Account WHERE CALENDAR_MONTH(CreatedDate) = 5
+  CORRECT: SELECT Id, Name FROM Account WHERE DAY_IN_WEEK(CreatedDate) = 2
+- NO math functions: ROUND, FLOOR, CEILING, ABS, etc.
+  SQL: SELECT ROUND(AnnualRevenue, 2) FROM Account
+  SOQL: Not supported
+- NO conditional functions: CASE WHEN, COALESCE, NULLIF, etc.
+  SQL: SELECT CASE WHEN Industry = 'Technology' THEN 'Tech' ELSE 'Other' END FROM Account
+  SOQL: Not supported
+- NO string functions except INCLUDES/EXCLUDES for multi-select picklists
+  SQL: SELECT UPPER(Name) FROM Account
+  SOQL: Not supported
+
+**OPERATORS:**
+- Supported: =, !=, <, >, <=, >=, LIKE, IN, NOT IN, INCLUDES, EXCLUDES
+  CORRECT: WHERE Industry = 'Technology'
+  CORRECT: WHERE AnnualRevenue >= 1000000
+  CORRECT: WHERE Industry IN ('Technology', 'Finance')
+  CORRECT: WHERE Industry NOT IN ('Government', 'Non-Profit')
+  CORRECT: WHERE Services__c INCLUDES ('Consulting')
+- NOT supported: REGEXP, BETWEEN, EXISTS, NOT EXISTS
+  SQL: WHERE Name REGEXP '^[A-Z]'
+  SOQL: Not supported
+
+**SORTING & LIMITING:**
+- ORDER BY: Fully supported
+  CORRECT: SELECT Id, Name FROM Account ORDER BY Name ASC
+  CORRECT: SELECT Id, Name FROM Account ORDER BY CreatedDate DESC, Name ASC
+  CORRECT: SELECT Id, Name FROM Account ORDER BY Name NULLS LAST
+- LIMIT: Maximum 2000 records, use smaller limits for better performance
+  CORRECT: SELECT Id, Name FROM Account LIMIT 100
+  CORRECT: SELECT Id, Name FROM Account LIMIT 2000
+  INCORRECT: SELECT Id, Name FROM Account LIMIT 5000
+- NO OFFSET: Not supported for pagination
+  SQL: SELECT Id, Name FROM Account LIMIT 10 OFFSET 20
+  SOQL: Not supported
+
+**DATA TYPES:**
+- picklist: Single-select dropdown, use = operator with string values
+  CORRECT: WHERE Industry = 'Technology'
+  CORRECT: WHERE Rating = 'Hot'
+- reference: Foreign key field, typically ends with Id
+  CORRECT: WHERE OwnerId = '00530000003OOwn'
+  CORRECT: WHERE AccountId = '0013000000UzXyz'
+- boolean: Use lowercase true/false
+  CORRECT: WHERE IsDeleted = false
+  CORRECT: WHERE Active__c = true
+- currency: Numeric field for money values
+  CORRECT: WHERE AnnualRevenue > 1000000
+  CORRECT: WHERE AnnualRevenue >= 500000.50
+- date: Date only, use YYYY-MM-DD format
+  CORRECT: WHERE LastActivityDate = 2025-05-28
+  CORRECT: WHERE SLAExpirationDate__c >= 2025-01-01
+- datetime: Date and time, use YYYY-MM-DDThh:mm:ssZ format
+  CORRECT: WHERE CreatedDate >= 2025-05-28T10:30:00Z
+  CORRECT: WHERE LastModifiedDate = 2025-05-28T00:00:00Z
+- double/int: Numeric fields
+  CORRECT: WHERE NumberOfEmployees > 100
+  CORRECT: WHERE NumberofLocations__c >= 5.5
+- string/textarea: Text fields, use single quotes
+  CORRECT: WHERE Name = 'Acme Corporation'
+  CORRECT: WHERE Description = 'Leading tech company'
+- phone/url/email: Specialized string fields, treat as strings
+  CORRECT: WHERE Phone = '555-1234'
+  CORRECT: WHERE Website = 'https://example.com'
+
+**COMMON MISTAKES TO AVOID:**
+- Using SELECT * (not allowed)
+  WRONG: SELECT * FROM Account
+  RIGHT: SELECT Id, Name, Industry FROM Account
+- Quoting date literals (dates must be unquoted)
+  WRONG: WHERE CreatedDate >= '2025-01-01'
+  RIGHT: WHERE CreatedDate >= 2025-01-01
+- Using SQL JOIN syntax (not supported)
+  WRONG: SELECT Account.Name FROM Account JOIN Contact ON Account.Id = Contact.AccountId
+  RIGHT: Use relationship traversal (not applicable in this use case)
+- Using BETWEEN operator (not supported)
+  WRONG: WHERE CreatedDate BETWEEN 2025-01-01 AND 2025-12-31
+  RIGHT: WHERE CreatedDate >= 2025-01-01 AND CreatedDate <= 2025-12-31
+- Using uppercase TRUE/FALSE/NULL (must be lowercase)
+  WRONG: WHERE Active__c = TRUE
+  RIGHT: WHERE Active__c = true
+- Using underscore _ in LIKE patterns (only % supported)
+  WRONG: WHERE Name LIKE 'A_me%'
+  RIGHT: WHERE Name LIKE 'A%me%'
+- Mixing aggregate and non-aggregate fields without GROUP BY
+  WRONG: SELECT Name, COUNT(Id) FROM Account
+  RIGHT: SELECT Industry, COUNT(Id) FROM Account GROUP BY Industry
+
+**EXAMPLE QUERIES:**
+- Basic selection: SELECT Id, Name, Industry FROM Account WHERE Industry = 'Technology'
+- Date filtering: SELECT Id, Name FROM Account WHERE CreatedDate >= 2025-01-01
+- Multiple conditions: SELECT Id, Name FROM Account WHERE Name LIKE '%Corp%' AND Industry IN ('Technology', 'Finance')
+- Aggregation: SELECT Industry, COUNT(Id) FROM Account GROUP BY Industry
+- Boolean and numeric: SELECT Id, Name FROM Account WHERE Active__c = true AND NumberOfEmployees > 100
+- Date functions: SELECT Id, Name FROM Account WHERE CALENDAR_YEAR(CreatedDate) = 2025
+- Null checks: SELECT Id, Name FROM Account WHERE ParentId = null
+- Multi-select picklist: SELECT Id, Name FROM Account WHERE Services__c INCLUDES ('Consulting;Support')
+- Sorting and limiting: SELECT Id, Name FROM Account ORDER BY Name ASC LIMIT 50
+
+***EXECUTION INSTRUCTIONS. IMPORTANT!***
+After generating the core SOQL (and nothing else), always make sure you wrap it exactly as:
+
+    SELECT * 
+      FROM {integration_name}(
+        /* your generated SOQL goes here, without a trailing semicolon */
+      )
+
+Return only that wrapper call.
+
+"""