Google Drive API含连字符文件名的contains查询异常求助

问题背景 #

使用Google API PHP Client 2.6.0操作Google Drive，按文件名搜索格式为Task-$task_id-Esercizi Ritmici.XXX的文件（如Task-1-Esercizi Ritmici.mp3、Task-36-Esercizi Ritmici.mp3）时出现异常：

• 搜索Task-3-Esercizi Ritmici时，传入name contains 'Task-3-Esercizi Ritmici'会匹配所有同格式文件
• 搜索Task-1-Esercizi Ritmici时则返回预期结果
• 进一步测试：name contains 'Task-3-E'/Task-3-Ese能正确匹配，但name contains 'Task-3-Esercizi'又会匹配全部文件，且API测试工具中也存在该问题，排除客户端问题

1. 异常原因 #

Google Drive的搜索依赖全文检索分词机制，并非简单的子字符串匹配：

• 连字符-会被分词器视为分隔符，将Task-3-Esercizi拆分为Task、3、Esercizi等独立词元
• 当搜索Task-3-Esercizi时，系统实际匹配的是所有包含Esercizi词元的文件（所有同格式文件都包含这个词）
• 而Task-1-Esercizi的情况中，1作为单个数字词元，和Task、Esercizi组合后，匹配的独特性更高，不会触发全局匹配
• 当搜索词较短（如Task-3-E）时，分词器无法拆分出独立的Esercizi词元，因此能精准匹配目标文件

2. 无需指定扩展名的正确查询方式 #

以下几种方式可避开分词干扰，实现精准匹配：

• 正则前缀匹配：使用matches运算符结合正则开头锚点，强制匹配文件名开头的指定字符串

  q: "name matches '^Task-3-Esercizi Ritmici'"
  

• 精确短语匹配：将核心短语用双引号包裹，强制系统匹配完整短语（注意参数中双引号需转义）

  q: "name contains 'Task-3-\"Esercizi Ritmici\"'"
  

• 开头匹配：使用starts with运算符，直接匹配以指定字符串开头的文件名，完全避开分词问题

  q: "name starts with 'Task-3-Esercizi Ritmici'"
  

3. 可行的文件名修改方案 #

如果必须通过改名避免搜索歧义，推荐以下几种格式：

• 下划线替换连字符：将-换成_，下划线不会被分词器拆分，整个前缀会被识别为连续单元

  Task_3_Esercizi Ritmici.mp3
  

• 括号包裹task_id：用括号将task_id包裹，让Task[3]成为一个独特的分词单元

  Task[3]-Esercizi Ritmici.mp3
  

• 空格分隔各部分：在连字符前后添加空格，让Task - 3成为独立的组合词元，减少误匹配

  Task - 3 - Esercizi Ritmici.mp3
  

内容的提问来源于stack exchange，提问作者davide ferrè