Ordenar los resultados en REST ($orderby)

La ordenación define la secuencia de registros devueltos y respalda la paginación estable. En REST, Data API Builder (DAB) usa el $orderby parámetro de consulta para ordenar los resultados antes de aplicar $first o $after. Si omite $orderby, DAB tiene como valor predeterminado ordenar por la clave principal (ascendente).

Nota:

Para las claves principales compuestas, DAB ordena por la secuencia de columnas de base de datos.

Vaya a la versión de GraphQL de este documento.

Información general

Concepto	Description
Parámetro de consulta	$orderby
Tokens de dirección	asc, desc
Orden predeterminado	Clave principal ascendente
Orden de varios campos	Lista de campos separados por comas
Desempate	Campos de clave principal restantes anexados automáticamente

Patrón de uso

GET /api/{entity}?$orderby=FieldA [asc|desc], FieldB desc

Example

Ordene los libros por año descendente y, a continuación, título ascendente.

GET /api/books?$orderby=year desc, title asc&$first=5

Conceptual SQL

SELECT TOP (5)
  id,
  sku_title AS title,
  year
FROM dbo.books
ORDER BY year DESC, sku_title ASC, id ASC;

Respuesta de ejemplo

{
  "value": [
    { "id": 7, "title": "Dune Messiah", "year": 1969 },
    { "id": 6, "title": "Dune", "year": 1965 },
    { "id": 3, "title": "Foundation", "year": 1951 },
    { "id": 1, "title": "I, Robot", "year": 1950 },
    { "id": 8, "title": "The Martian Chronicles", "year": 1950 }
  ]
}

Reglas

Rule	Detalle
Delimitador	Coma + espacio en blanco opcional
Palabras clave de dirección	asc (valor predeterminado), desc
Distinción entre mayúsculas y minúsculas	Los nombres de campo distinguen mayúsculas de minúsculas.
Campo desconocido	Devuelve 400 Invalid orderby column requested
Sintaxis no admitida	Devuelve 400 OrderBy property is not supported.

Errores de ejemplo

Nombre de campo no válido:

400 Invalid orderby column requested: publishedYear

Token no admitido:

400 OrderBy property is not supported.

Interacción con $select

Cuando se ordena por un campo que no está presente en $select, DAB lo captura internamente para ordenar o crear el cursor, pero lo omite de la carga final.

Configuración pertinente

{
  "entities": {
    "Book": {
      "source": {
        "object": "dbo.books",
        "type": "table"
      },
      "mappings": {
        "sku_title": "title"
      }
    }
  }
}

Ejemplo de configuración

{
  "runtime": {
    "pagination": {
      "default-page-size": 100,
      "max-page-size": 100000
    }
  },
  "entities": {
    "Book": {
      "source": {
        "type": "table",
        "object": "dbo.books"
      },
      "mappings": {
        "sku_title": "title",
        "sku_price": "price"
      },
      "relationships": {
        "book_category": {
          "cardinality": "one",
          "target.entity": "Category",
          "source.fields": [ "category_id" ],
          "target.fields": [ "id" ]
        }
      }
    },
    "Category": {
      "source": {
        "type": "table",
        "object": "dbo.categories"
      },
      "relationships": {
        "category_books": {
          "cardinality": "many",
          "target.entity": "Book",
          "source.fields": [ "id" ],
          "target.fields": [ "category_id" ]
        }
      }
    }
  }
}

Consulte también

Concepto	REST	GraphQL	Propósito
Projection	$select	items	Elección de los campos que se van a devolver
Filtros	$filter	filtro	Restricción de filas por condición
Ordenación	$orderby	orderBy	Definición del criterio de ordenación
Tamaño de página	$first	primero	Limitar el número de elementos por página
Continuación	$after	después	Continuar desde la última página con un cursor

Nota:

Las palabras clave rest comienzan por $, siguiendo las convenciones de OData.