How to fix ParsingException: Unknown key for a START_OBJECT in [query] in Elasticsearch

# The error message typically looks like:
# "parsing_exception: Unknown key for a START_OBJECT in [filter]"
# "reason": "Unknown key for a START_OBJECT in [filter]",
# "line": 3,
# "col": 5

# Run the query with verbose error output
curl -X GET "localhost:9200/my-index/_search?error_trace=true" -u "username:password" -H 'Content-Type: application/json' -d'
{
  "query": {
    "match_all": {}
  },
  "filter": {
    "term": { "status": "active" }
  }
}
'

# INCORRECT - filter at root level
curl -X GET "localhost:9200/my-index/_search" -u "username:password" -H 'Content-Type: application/json' -d'
{
  "query": {
    "match_all": {}
  },
  "filter": {
    "term": { "status": "active" }
  }
}
'

# CORRECT - filter inside bool query
curl -X GET "localhost:9200/my-index/_search" -u "username:password" -H 'Content-Type: application/json' -d'
{
  "query": {
    "bool": {
      "must": [
        { "match_all": {} }
      ],
      "filter": [
        { "term": { "status": "active" } }
      ]
    }
  }
}
'

# Alternative: Use bool query with only filter (more efficient)
curl -X GET "localhost:9200/my-index/_search" -u "username:password" -H 'Content-Type: application/json' -d'
{
  "query": {
    "bool": {
      "filter": [
        { "term": { "status": "active" } },
        { "range": { "created_at": { "gte": "2024-01-01" } } }
      ]
    }
  }
}
'

# INCORRECT - should clause not in array
curl -X GET "localhost:9200/my-index/_search" -u "username:password" -H 'Content-Type: application/json' -d'
{
  "query": {
    "bool": {
      "should": {
        "match": { "title": "error" }
      }
    }
  }
}
'

# CORRECT - should clause in array
curl -X GET "localhost:9200/my-index/_search" -u "username:password" -H 'Content-Type: application/json' -d'
{
  "query": {
    "bool": {
      "should": [
        { "match": { "title": "error" } },
        { "match": { "description": "exception" } }
      ],
      "minimum_should_match": 1
    }
  }
}
'

# CORRECT - combining multiple bool clauses
curl -X GET "localhost:9200/my-index/_search" -u "username:password" -H 'Content-Type: application/json' -d'
{
  "query": {
    "bool": {
      "must": [
        { "match": { "status": "published" } }
      ],
      "should": [
        { "match": { "title": "elasticsearch" } },
        { "match": { "tags": "database" } }
      ],
      "filter": [
        { "range": { "created_at": { "gte": "2024-01-01" } } }
      ],
      "must_not": [
        { "term": { "archived": true } }
      ],
      "minimum_should_match": 1
    }
  }
}
'

# Use jq to validate JSON syntax
echo '{
  "query": {
    "bool": {
      "filter": [
        { "term": { "status": "active" } }
      ]
    }
  }
}' | jq .

# Use Python to validate and format
python3 << 'EOF'
import json

query = '''
{
  "query": {
    "bool": {
      "filter": [
        { "term": { "status": "active" } }
      ]
    }
  }
}
'''

try:
    parsed = json.loads(query)
    print("Valid JSON:")
    print(json.dumps(parsed, indent=2))
except json.JSONDecodeError as e:
    print(f"JSON Error: {e}")
EOF

# INCORRECT - using numeric keys in fields object
curl -X GET "localhost:9200/my-index/_search" -u "username:password" -H 'Content-Type: application/json' -d'
{
  "query": { "match_all": {} },
  "_source": {
    "0": "field1",
    "1": "field2"
  }
}
'

# CORRECT - use array for fields
curl -X GET "localhost:9200/my-index/_search" -u "username:password" -H 'Content-Type: application/json' -d'
{
  "query": { "match_all": {} },
  "_source": ["field1", "field2"]
}
'

# INCORRECT - numeric keys in aggregations
curl -X GET "localhost:9200/my-index/_search" -u "username:password" -H 'Content-Type: application/json' -d'
{
  "aggs": {
    "0": {
      "terms": { "field": "category" }
    }
  }
}
'

# CORRECT - use descriptive aggregation names
curl -X GET "localhost:9200/my-index/_search" -u "username:password" -H 'Content-Type: application/json' -d'
{
  "aggs": {
    "categories": {
      "terms": {
        "field": "category.keyword",
        "size": 10
      }
    }
  }
}
'

# Elasticsearch 2.x syntax (deprecated)
curl -X GET "localhost:9200/my-index/_search" -u "username:password" -H 'Content-Type: application/json' -d'
{
  "query": {
    "filtered": {
      "query": { "match_all": {} },
      "filter": { "term": { "status": "active" } }
    }
  }
}
'

# Elasticsearch 5.x+ syntax (current)
curl -X GET "localhost:9200/my-index/_search" -u "username:password" -H 'Content-Type: application/json' -d'
{
  "query": {
    "bool": {
      "must": { "match_all": {} },
      "filter": { "term": { "status": "active" } }
    }
  }
}
'

# Update deprecated query types
# Old: "and", "or", "not" filters
# New: bool query with "must", "should", "must_not"

# Old syntax (Elasticsearch 2.x)
{
  "query": {
    "filtered": {
      "filter": {
        "and": [
          { "term": { "status": "active" } },
          { "range": { "price": { "gte": 10 } } }
        ]
      }
    }
  }
}

# New syntax (Elasticsearch 5.x+)
{
  "query": {
    "bool": {
      "filter": [
        { "term": { "status": "active" } },
        { "range": { "price": { "gte": 10 } } }
      ]
    }
  }
}