apache/druid · error · MSQException

ColumnNameRestricted

ColumnNameRestricted

Error message

ColumnNameRestrictedFault: __boost is a restricted column name

What it means

Thrown by QueryKitUtils.verifyRowSignature when the query's output signature contains the reserved partition-boost column (__boost, PARTITION_BOOST_COLUMN). MSQ uses __boost internally to influence partition weighting, so user queries must not define a column with that name; doing so would collide with internal machinery.

Solutions

1. Rename the user column/alias away from __boost, e.g. AS boost_col.
2. Filter out or exclude the __boost column from the SELECT projection.
3. If the source table has a __boost column, exclude it during ingestion or rename it upstream.

Example fix

// before
SELECT __boost, other_col FROM druid.tbl
// after
SELECT __boost AS boost_value, other_col FROM druid.tbl

for (String col : signature.getColumnNames()) {
  if ("__boost".equals(col)) throw new IllegalArgumentException("Rename column __boost before using MSQ");
}

try {
  QueryKitUtils.verifyRowSignature(signature);
} catch (MSQException e) {
  // prompt user to rename reserved columns and resubmit
}

When it happens

Trigger: A query (e.g. an INSERT/SELECT producing output for partitioning) whose result RowSignature includes a column literally named __boost, typically because a source column is named __boost or an expression aliases to __boost.

Common situations: Ingesting data that already contains a column named __boost; renaming an expression with AS "__boost"; schema copied verbatim from data files that happen to include reserved names.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Cannot mix sortable and unsortable key columns
• Invalid bucketByCount
• Must provide at least one range
• Actual Row count mismatch. Expected
• Aggregation [ ] does not support column [ ] of type [ ]…

AI-assisted analysis of apache/druid@9b90983fd2 (2026-09-07). Data as JSON: /api/errors/89d58b2b4439a323. Report an issue: GitHub.

Appendix: source

Thrown at multi-stage-query/src/main/java/org/apache/druid/msq/querykit/QueryKitUtils.java:133

  {
    if (Granularities.ALL.equals(segmentGranularity)) {
      return clusterBy;
    } else {
      final List<KeyColumn> newColumns = new ArrayList<>(clusterBy.getColumns().size() + 1);
      newColumns.add(new KeyColumn(QueryKitUtils.SEGMENT_GRANULARITY_COLUMN, KeyOrder.ASCENDING));
      newColumns.addAll(clusterBy.getColumns());
      return new ClusterBy(newColumns, 1);
    }
  }

  /**
   * Verifies the {@link RowSignature} and throws an appropriate exception if it is invalid or uses restricted column
   * names
   */
  public static void verifyRowSignature(final RowSignature signature)
  {
    if (signature.contains(QueryKitUtils.PARTITION_BOOST_COLUMN)) {
      throw new MSQException(new ColumnNameRestrictedFault(QueryKitUtils.PARTITION_BOOST_COLUMN));
    } else if (signature.contains(QueryKitUtils.SEGMENT_GRANULARITY_COLUMN)) {
      throw new MSQException(new ColumnNameRestrictedFault(QueryKitUtils.SEGMENT_GRANULARITY_COLUMN));
    }
  }

  /**
   * Adds {@link #SEGMENT_GRANULARITY_COLUMN} to a {@link RowSignature} if needed. Signature should be verified prior
   * to calling this function to ensure that {@link #SEGMENT_GRANULARITY_COLUMN} is not passed in by the user
   */
  public static RowSignature signatureWithSegmentGranularity(
      final RowSignature signature,
      final Granularity segmentGranularity
  )
  {
    if (Granularities.ALL.equals(segmentGranularity)) {
      return signature;
    } else {
      return RowSignature.builder()

View on GitHub (pinned to 9b90983fd2)