Skip to content

Latest commit

 

History

History
192 lines (156 loc) · 11.6 KB

LeaderboardMatrix.md

File metadata and controls

192 lines (156 loc) · 11.6 KB
Raw

LeaderboardMatrix

Types

  • DimensionName: string dimension name in a matrix

  • FeatureName: string feature name in a matrix

  • MatrixEntry:

    • id: ID entry id
    • ranks: { [dimension: string]: { [feature: string]: Rank } } entry ranks
    • scores: { [dimension: string]: { [feature: string]: Score } } entry scores

  • MatrixLeaderboardQueryFilter: filter query results

    • dimensions?: DimensionName[] dimensions to include in the result. If undefined or empty, all dimensions will be included
    • features?: FeatureName[] features to include in the result. If undefined or empty, all features will be included

❗ Note: filters only affect the values returned, not the leaderboards searched (leaderboards searched are set using dimensionToSort and featureToSort)

Constructor

Arguments

Example

const mlb = new LeaderboardMatrix(client, "mlb:test", {
  dimensions: [
    { name: "global" },
    {
      name: "per-month",
      cycle: 'monthly'
    }
  ],
  features: [{
    name: "kills",
    options: {
      updatePolicy: 'replace',
      sortPolicy: 'high-to-low'
    }
  }, {
    name: "seconds",
    options: {
      updatePolicy: 'best',
      sortPolicy: 'low-to-high'
    }
  }]
});

Leaderboards

  • getLeaderboard(dimension: DimensionName, feature: FeatureName, time?: Date): Leaderboard | null get a leaderboard in the matrix

    • dimension: DimensionName dimension name
    • feature: FeatureName feature name
    • time?: Date time (for periodic leaderboards). If not provided, now() will be used

    Note: returns null if the dimension/feature pair is invalid

  • getRawLeaderboard(dimension: DimensionName, feature: FeatureName): Leaderboard | PeriodicLeaderboard | null get the raw leaderboard object

    The difference with getLeaderboard is that you get the underlying periodic leaderboard wrapper instead of a specific leaderboard of a periodic cycle.

Insert/update entries

Remember that insert/update is the same operation.

  • update(entries: MatrixEntryUpdateQuery | MatrixEntryUpdateQuery[], dimensions?: DimensionName[], updatePolicy?: UpdatePolicy): Promise<any> update one or more entries. If one of the entries does not exists, it will be created

    • entries: MatrixEntryUpdateQuery | MatrixEntryUpdateQuery[] entry or list of entries to update
      • MatrixEntryUpdateQuery:
        • id: ID entry id
        • values: { [feature: string] : number | Score } features to update
    • dimensions?: DimensionName[] filter the update to only this dimensions. If empty or undefined, all dimensions will be updated
    • updatePolicy?: UpdatePolicy override every default update policy only for this update

    The update behaviour is determined by the sort and update policies of each leaderboard in the matrix (or overriden by updatePolicy)

    Example

    await mlb.update([{
  id: "player-1",
  values: {
    kills: 27,
    time: 427
  }
}], ["global"]); // update only the global dimension

Remove entries

  • remove(ids: ID | ID[], dimensions?: DimensionName[], features?: FeatureName[]): Promise<void> remove one or more entries from the leaderboards
    • ids: ID | ID[] ids to remove
    • dimensions?: DimensionName[] dimensions to remove from. If empty or undefined, entries will be removed from all dimensions
    • features?: FeatureName[] features to remove from. If empty or undefined, entries will be removed from all features

Find entries

  • find(ids: ID, filter?: MatrixLeaderboardQueryFilter): Promise<MatrixEntry | null> retrieve an entry. If it doesn't exist, it returns null

    Example

    await mlb.find("player-1");
    {
  id: "player-1",
  ranks: {
    global: {
      kills: 1,
      time: 1
    }
  },
  scores: {
   global: {
     kills: 27,
     time: 427
   }
 }
}

List entries

When you retrieve a list of entries, you must specify the dimension and feature you want to sort. Then the filter is applied and you can retrieve data from all other leaderboards in the matrix.

  • list(dimensionToSort: DimensionName, featureToSort: FeatureName, lower: Rank, upper: Rank, filter?: MatrixLeaderboardQueryFilter): Promise<MatrixEntry[]> retrieve entries between ranks

  • top(dimensionToSort: DimensionName, featureToSort: FeatureName, max: number = 10, filter?: MatrixLeaderboardQueryFilter): Promise<MatrixEntry[]> retrieve the top entries

  • bottom(dimensionToSort: DimensionName, featureToSort: FeatureName, max: number = 10, filter?: MatrixLeaderboardQueryFilter): Promise<MatrixEntry[]> retrieve the bottom entries (from worst to better)

  • around(dimensionToSort: DimensionName, featureToSort: FeatureName, id: ID, distance: number, fillBorders: boolean = false, filter?: MatrixLeaderboardQueryFilter): Promise<MatrixEntry[]> retrieve the entries around an entry

    • dimensionToSort: DimensionName dimension to perform the sorting
    • featureToSort: FeatureName feature to perform the sorting
    • id: ID id of the entry at the center
    • distance: number number of entries at each side of the queried entry
    • fillBorders?: FeatureName include entries at the other side if the entry is too close to one of the borders
    • filter?: MatrixLeaderboardQueryFilter filter to apply

    For details, see the simple leaderboard version of around().

  • showcase(dimensionOrder: DimensionName[], featureToSort: FeatureName, threshold: number, filter: MatrixLeaderboardQueryFilter): Promise<MatrixShowcase | null> returns the top threshold entries from a leaderboard that has at least threshold entries

    The dimensionOrder defines the order to check the leaderboards, and featureToSort the feature (which is fixed).
    If no dimension meet the threshold, then the dimension with the highest number of entries will be used to query the entries.
    If all dimensions have 0 entries, then returns null

    Note: this function actually does two round trips to Redis!

    Return

    MatrixShowcase:

Information

  • count(): Promise<MatrixCount> retrieve the number of entries in each leaderboard

    Return

    MatrixCount:
    • { [dimension: string ]: { [feature: string]: number } }