Pandas参数化SQL查询取DataFrame首行触发iloc越界IndexError

• 固定值作为SQL筛选条件，查询结果写入Pandas DataFrame时，可正常引用返回数据
• 改造为支持变量传入的参数化查询后，触发报错：IndexError: single positional indexer is out-of-bounds
• 业务逻辑上该查询始终应当仅返回1行数据，对应问题代码如下：

def getMapData(unique_id):
    if unique_id is None:
       unique_id = "abc123" #set default value
    loc_query = pd.read_sql_query('''
                                  SELECT LAT, LON, [firstname] + ' ' + [lastname] AS full_name FROM PROPERTY
                                  WHERE ((unique_id)=(?))''', connection, params=(unique_id,))
    #Convert SQL to DF:
    loc_df = pd.DataFrame(loc_query, columns = ['LAT', 'LON', 'full_name'])
    return(loc_df['LAT'].iloc[0], loc_df['LON'].iloc[0], loc_df['full_name'].iloc[0])

• 先验证查询返回结果行数
  报错本质是调用.iloc[0]时DataFrame是空的，没有任何行数据，先在return前加一行print(len(loc_query), unique_id, type(unique_id))，确认实际传入参数化查询的值、类型是否和写死固定值时完全一致。
• 排查参数类型不匹配问题
  绝大多数这类问题都是参数类型不匹配导致的：比如写死固定值时是字符串'abc123'，但实际传入函数的unique_id可能是整数、带前后空格的字符串、字节类型，或者大小写和数据库存储值不一致，导致WHERE条件匹配不到任何数据。
• 排查冗余的DataFrame构造逻辑
  pd.read_sql_query本身返回的就是Pandas DataFrame对象，额外再用pd.DataFrame()包裹、手动指定columns的操作是多余的，如果SQL返回的字段名和你指定的列名存在大小写、空格差异，会直接生成全空值的DataFrame，哪怕SQL实际查到了数据也会被覆盖为空。
• 直接打印SQL执行结果验证
  去掉二次构造DataFrame的逻辑后，直接打印loc_query内容，确认是否真的返回了预期的1行数据。

def getMapData(unique_id):
    if unique_id is None:
       unique_id = "abc123" # 设置默认值
    # 统一预处理参数，避免前后空格、类型不匹配问题
    unique_id = str(unique_id).strip()
    # read_sql_query直接返回DataFrame，无需二次构造
    loc_df = pd.read_sql_query('''
                                  SELECT LAT, LON, [firstname] + ' ' + [lastname] AS full_name FROM PROPERTY
                                  WHERE unique_id = ?
                                  ''', connection, params=(unique_id,))
    # 增加空结果判断，避免直接取iloc[0]报错
    if len(loc_df) == 0:
        raise ValueError(f"未查询到unique_id为{unique_id}的对应数据")
    return(loc_df['LAT'].iloc[0], loc_df['LON'].iloc[0], loc_df['full_name'].iloc[0])

• 报错的直接原因是调用.iloc[0]取第一行数据时，DataFrame为空，没有可索引的行
• 最高发的诱因是多余的pd.DataFrame(loc_query, columns=[...])二次构造操作，字段名不匹配时会覆盖原查询结果生成空表
• 其次是传入参数和数据库存储值的类型、格式不匹配，导致WHERE条件匹配不到任何数据

内容的提问来源于stack exchange，提问作者like2think