Api clients / JavaScript / V3 / Methods

Jan. 09, 2023

Save Rule | JavaScript API Client V3 (Deprecated)

This version of the JavaScript API client has been deprecated in favor of the latest version of the JavaScript API client.

Required API Key: any key with the editSettings ACL

Method signature

index.saveRule(
  object Rule,
  {
    forwardToReplicas: boolean
  },
  callback
)

See code examples

About this method

Create or update a single Rule.

Examples

Save a Rule

Copy

Copy
$rule = array(
    'objectID' => 'a-rule-id',
    'condition' => array(
        'pattern'   => 'smartphone',
        'anchoring' => 'contains',
    ),
    'consequence' => array(
        'params' => array(
            'filters' => 'category = 1',
        )
    )
);

// Optionally, to disable the rule
$rule['enabled'] = false;

// Optionally, to add validity time ranges
$rule['validity'] = array(
  array(
    'from' => time(),
    'until' => time() + 10*24*60*60,
  )
);

$index->saveRule($rule);

Copy
forward_to_replicas = true

rule = {
  objectID: 'a-rule-id',
  condition: {
    pattern: 'smartphone',
    anchoring: 'contains'
  },
  consequence: {
    params: {
      filters: 'category = 1'
    }
  }
}

# Optionally, to disable the rule
rule['enabled'] = false

# Optionally, to add validity time ranges
# (with `require 'date'`)
rule['validity'] = [
  {
    from: Time.now.to_i,
    until: (DateTime.now + 10).to_time.to_i,
  }
]

# Save the Rule.
index.save_rule('a-rule-id', rule)
# Save the Rule and wait the end of indexing.
index.save_rule!('a-rule-id', rule)
# Save the Rule, and forward it to all replicas of the index.
response = index.save_rule('a-rule-id', rule, forward_to_replicas)

Copy
const rule = {
  objectID: 'a-rule-id',
  condition: {
    pattern: 'smartphone',
    anchoring: 'contains'
  },
  consequence: {
    params: {
      filters: 'category = 1'
    }
  }
};

// Optionally, to disable the rule
rule['enabled'] = false;

// Optionally, to add valitidy time ranges
rule['validity'] = [
  {
    'from': Math.floor(Date.now()/1000),
    'until': Math.floor(Date.now()/1000) + 10*24*60*60,
  }
];

// Save the Rule.
index.saveRule(rule, (err, content) => {
  if (err) throw err;

  console.log(content);
});

// Save the Rule, and forward it to all replicas of the index.
index.saveRule(rule, {forwardToReplicas: true}, (err, content) => {
  if (err) throw err;

  console.log(content);
});

Copy
rule = {
    'objectID': 'a-rule-id',
    'condition': {
        'pattern': 'smartphone',
        'anchoring': 'contains'
    },
    'consequence': {
        'params': {
            'filters': 'category = 1'
        }
    }
}

# Optionally, to disable the rule
rule['enabled'] = False

# Optionally, to add validity time ranges
# Python 2 (with `time` and `datetime.timedelta` imports)
rule['validity'] = [
    {
        'from': int(time.time()),
        'until': int(time.time() + timedelta(days=10).total_seconds())
    }
]
# Python 3 (with `datetime.{datetime,timedelta}` imports)
rule['validity'] = [
    {
        'from': int((datetime.datetime.utcnow().timestamp())),
        'until': int(
            (datetime.datetime.utcnow() + timedelta(days=10)).timestamp())
    }
]

# Save the Rule.
response = index.save_rule(rule)

# Save the Rule, and forward it to all replicas of the index.
response = index.save_rule(rule, {
    'forwardToReplicas': True
})

Copy
Rule ruleToSave = new Rule
{
    ObjectID = "a-rule-id",
    Enabled = false,
    Condition = new Condition { Anchoring = "contains", Pattern = "smartphone" },
    Consequence = new Consequence
    {
        Params = new ConsequenceParams
        {
            AutomaticFacetFilters = new List<AutomaticFacetFilter>
            {
                new AutomaticFacetFilter { Facet = "category = 1" }
            }
        }
    },
    Validity = new List<TimeRange>
    {
        new TimeRange
        {
            From = new DateTimeOffset(DateTime.UtcNow).ToUnixTimeSeconds(),
            Until = new DateTimeOffset(DateTime.UtcNow.AddDays(10)).ToUnixTimeSeconds()
        }
    }
  };

index.SaveRule(rule, forwardToReplicas: false);

// Asynchronous
await index.SaveRuleAsync(rule, forwardToReplicas: false);

Copy
Condition condition = new Condition()
        .setPattern("smartphone")
        .setAnchoring("contains");

ConsequenceParams params = (ConsequenceParams) new ConsequenceParams()
        .setFilters("category = 1");

Consequence consequence =  new Consequence()
        .setParams(params);

Rule rule = new Rule()
        .setObjectID("a-unique-identifier")
        .setCondition(condition)
        .setConsequence(consequence);

// Optionally, to disable the rule
rule.setEnabled(false);

// Optionally, to add validity time ranges
List<TimeRange> validity =
        Collections.singletonList(
                new TimeRange(
                        OffsetDateTime.now(ZoneOffset.UTC),
                        OffsetDateTime.now(ZoneOffset.UTC).plusDays(10));
rule.setValidity(validity);

index.saveRule(rule);

// Asynchronous
index.saveRuleAsync(rule);

Copy
forwardToReplicas := opt.ForwardToReplicas(false)

rule := search.Rule{
  ObjectID:  "a-rule-id",
  Condition: search.RuleCondition{Anchoring: search.Contains, Pattern: "smartphone"},
  Consequence: search.RuleConsequence{
    Params: &search.RuleParams{
      QueryParams: search.QueryParams{
        Filters: opt.Filters("category = 1"),
      },
    },
  },
  Enabled: opt.Enabled(false), // Optionally, to disable the rule
  Validity: []search.TimeRange{ // Optionally, to add validity time ranges
    {
      From:  time.Now(),
      Until: time.Now().AddDate(0, 0, 10),
    },
  },
}

res, err := index.SaveRule(rule, forwardToReplicas)

Copy
val from = ZonedDateTime.now(ZoneId.of("UTC").normalized());
val until = from.plusDays(10);

val ruleToSave = Rule(
  objectID = "a-rule-id",
  enabled = Some(false), // Optionally, to disable the rule
  validity = Some(Seq(TimeRange(from, until))), // Optionally, to add validity time ranges
  condition = Condition(
    pattern = "smartphone",
    anchoring = "contains",
  ),
  consequence = Consequence(
    params = Some(Map("filters" -> "category = 1")),
  ),
)
client.execute {
  save rule ruleToSave inIndex "index_name"
}

Copy
val rule = Rule(
    objectID = ObjectID("a-rule-id"),
    enabled = false,
    condition = Condition(
        pattern = Pattern.Literal("smartphone"),
        anchoring = Anchoring.Contains,
        alternative = Alternatives.True
    ),
    consequence = Consequence(
        query = Query(filters = "category = 1")
    ),
    validity = listOf(TimeRange(0, 10))
)

index.saveRule(rule, forwardToReplicas = true)

Save a Rule with alternatives enabled

Copy

Copy
$rule = array(
    'objectID' => 'a-rule-id',
    'condition' => array(
        'pattern'   => 'smartphone',
        'anchoring' => 'contains',
        'alternatives' => true
    ),
    'consequence' => array(
        'params' => array(
            'filters' => 'category = 1',
        )
    )
);
$index->saveRule($rule);

Copy
rule = {
  objectID: 'a-rule-id',
  condition: {
    pattern: 'smartphone',
    anchoring: 'contains',
    alternatives: true
  },
  consequence: {
    params: {
      filters: 'category = 1'
    }
  }
}
index.save_rule('a-rule-id', rule)

Copy
const rule = {
  objectID: 'a-rule-id',
  condition: {
    pattern: 'smartphone',
    anchoring: 'contains',
    alternatives: true
  },
  consequence: {
    params: {
      filters: 'category = 1'
    }
  }
};
index.saveRule(rule, (err, content) => {
  if (err) throw err;
  console.log(content);
});

Copy
rule = {
    'objectID': 'a-rule-id',
    'condition': {
        'pattern': 'smartphone',
        'anchoring': 'contains',
        'alternatives': True
    },
    'consequence': {
        'params': {
            'filters': 'category = 1'
        }
    }
}
response = index.save_rule(rule)

Copy
Rule ruleToSave = new Rule
{
    ObjectID = "a-rule-id",
    Condition = new Condition { Anchoring = "contains", Pattern = "smartphone", Alternatives = true },
    Consequence = new Consequence
    {
        Params = new ConsequenceParams
        {
            Filters = "category = 1"
        }
    },
  };
index.SaveRule(rule);

Copy
Condition condition = new Condition()
        .setPattern("smartphone")
        .setAnchoring("contains")
        .setAlternatives(true);
ConsequenceParams params = (ConsequenceParams) new ConsequenceParams()
        .setFilters("category = 1");
Consequence consequence =  new Consequence()
        .setParams(params);
Rule rule = new Rule()
        .setObjectID("a-rule-id")
        .setCondition(condition)
        .setConsequence(consequence);
index.saveRule(rule);

Copy
rule := search.Rule{
  ObjectID:  "a-rule-id",
  Condition: search.RuleCondition{Anchoring: search.Contains, Pattern: "smartphone", Alternatives: true},
  Consequence: search.RuleConsequence{
    Params: &search.RuleParams{
      QueryParams: search.QueryParams{
        Filters: opt.Filters("category = 1"),
      },
    },
  },
}
res, err := index.SaveRule(rule)

Copy
val ruleToSave = Rule(
  objectID = "a-rule-id",
  condition = Condition(
    pattern = "smartphone",
    anchoring = "contains",
    alternatives = true
  ),
  consequence = Consequence(
    params = Some(Map("filters" -> "category = 1")),
  ),
)

client.execute {
  save rule ruleToSave inIndex "index_name"
}

Copy
val rule = Rule(
    objectID = ObjectID("a-rule-id"),
    condition = Condition(
        pattern = Pattern.Literal("smartphone"),
        anchoring = Anchoring.Contains
        alternatives = Alternatives.true
    ),
    consequence = Consequence(
        params = Params(filters = "category = 1")
    )
)
index.saveRule(rule)

Save a Rule with a context based condition

Copy

Copy
$rule = array(
    'objectID' => 'a-rule-id',
    'condition' => array(
        'context' => 'mobile',
    ),
    'consequence' => array(
        'params' => array(
            'filters' => 'release_date >= 1568498400',
        )
    )
);

$index->saveRule($rule);

Copy
rule = {
  objectID: 'a-rule-id',
  condition: {
    context: 'mobile'
  },
  consequence: {
    params: {
      filters: 'release_date >= 1568498400'
    }
  }
}

index.save_rule('a-rule-id', rule)

Copy
const rule = {
  objectID: 'a-rule-id',
  condition: {
    context: 'mobile'
  },
  consequence: {
    params: {
      filters: 'release_date >= 1568498400'
    }
  }
};

index.saveRule(rule, (err, content) => {
  if (err) throw err;

  console.log(content);
});

Copy
rule = {
    'objectID': 'a-rule-id',
    'condition': {
        'context': 'mobile'
    },
    'consequence': {
        'params': {
            'filters': 'release_date >= 1568498400'
        }
    }
}

response = movies.save_rule(rule)

Copy
Rule ruleToSave = new Rule
{
    ObjectID = "a-rule-id",
    Condition = new Condition { Context = "mobile"  },
    Consequence = new Consequence
    {
        Params = new ConsequenceParams
        {
            AutomaticFacetFilters = new List<AutomaticFacetFilter>
            {
                new AutomaticFacetFilter { Facet = "release_date >= 1568498400" }
            }
        }
    }
  };

index.SaveRule(rule, forwardToReplicas: false);

Copy
Condition condition = new Condition()
        .setContext("smartphone")

ConsequenceParams params = (ConsequenceParams) new ConsequenceParams()
        .setFilters("release_date >= 1568498400");

Consequence consequence =  new Consequence()
        .setParams(params);

Rule rule = new Rule()
        .setObjectID("a-unique-identifier")
        .setCondition(condition)
        .setConsequence(consequence);

index.saveRule(rule);

// Asynchronous
index.saveRuleAsync(rule);

Copy
forwardToReplicas := opt.ForwardToReplicas(false)

rule := search.Rule{
  ObjectID:  "a-rule-id",
  Condition: search.RuleCondition{Context: "mobile"},
  Consequence: search.RuleConsequence{
    Params: &search.RuleParams{
      QueryParams: search.QueryParams{
        Filters: opt.Filters("release_date >= 1568498400"),
      },
    },
  },
}

res, err := index.SaveRule(rule, forwardToReplicas)

Copy
val ruleToSave = Rule(
  objectID = "a-rule-id",
  condition = Condition(
    context = "mobile",
  ),
  consequence = Consequence(
    params = Some(Map("filters" -> "release_date >=  1568498400")),
  ),
)
client.execute {
  save rule ruleToSave inIndex "index"
}

Copy
val rule = Rule(
    objectID = ObjectID("a-rule-id"),
    condition = Condition(
        context = Context.Literal("mobile")
    ),
    consequence = Consequence(
        query = Query(filters = "release_date >= 1568498400")
    ),
)

index.saveRule(rule)

Parameters


            objectID

type: string

Required

Unique identifier for the Rule (format: [A-Za-z0-9_-]+).

Note that for some languages, the objectID is duplicated in the Rule.


            Rule

type: rule

Required

The rule object, its condition(s) and consequence(s).

{
  objectID: objectID,
  condition: condition,
  consequence: consequence
}


            forwardToReplicas

type: boolean

default: false

Optional

By default, this method applies only to the specified index. By making this true, the method will also send the Rule to all replicas.

Rule ➔ rule

`objectID`	type: string Required Must contain the same value as the objectID above.
`condition`	type: condition Optional Condition of the Rule, expressed using the following variables: `pattern`, `anchoring`, `context`. When the condition is not provided or is empty, the Rule is active for all queries to the relevant index. { "pattern": pattern, "anchoring": anchoring, "context": context }
`consequence`	type: consequence Required Consequence of the Rule. At least one of the following object must be used: params promote hide userData
`description`	type: string Optional This field is intended for Rule management purposes, in particular to ease searching for Rules and presenting them to human readers. It is not interpreted by the API.
`enabled`	type: boolean default: true Optional Whether the Rule is enabled. Disabled Rules remain in the index, but are not applied at query time.
`validity`	type: list of timeRange Optional By default, Rules are permanently valid. When validity periods are specified, the Rule applies only during those periods; it is ignored the rest of the time. The list must not be empty.

Rule ➔ rule ➔ condition


            pattern

type: string

Optional

Query pattern syntax

Query patterns are expressed as a string with a specific syntax. A pattern is a sequence of tokens, which can be either:

Facet value placeholder: {facet:$facet_name}. Example: {facet:brand}.
Literal: the world itself. Example: Algolia.

Special characters ({, }, : and \) must be escaped by preceding them with a backslash (\) if they are to be treated as literals.

This parameter goes hand in hand with the anchoring parameter. If you’re creating a Rule that depends on a specific query, you must specify the pattern and anchoring. The empty "" pattern is only allowed when anchoring is set to is.

Otherwise, you can omit both.


            anchoring

type: string, enum

Optional

{ is | startsWith | endsWith | contains }: Whether the pattern must match the beginning or the end of the query string, or both, or none.

This parameter goes hand in hand with the pattern parameter. If you’re creating a Rule that depends on a specific query, you must specify the pattern and anchoring.

Otherwise, you can omit both.


            context

type: string

Optional

Rule context (format: [A-Za-z0-9_-]+). When specified, the Rule is only applied when the same context is specified at query time (using the ruleContexts parameter). When absent, the Rule is generic and always applies (provided that its other conditions are met, of course).

Rule ➔ rule ➔ consequence

`params`	type: params Optional Additional search parameters. Any valid search parameter is allowed. Specific treatment is applied to these fields: `query`, `automaticFacetFilters`, `automaticOptionalFacetFilters`. { "query": query, "automaticFacetFilters": automaticFacetFilters, "automaticOptionalFacetFilters": automaticOptionalFacetFilters }
`promote`	type: list Optional Objects to promote as hits. Each object must contain the following fields: `objectID`, `position` { "objectID": objectID, "position": position }
`filterPromotes`	type: boolean default: false Optional Only use in combination with the `promote` consequence. When `true`, promoted results will be restricted to match the filters of the current search. When `false`, the promoted results will show up regardless of the filters. { "promote": { "objectID": objectID, "position": position }, "filterPromotes": true }
`hide`	type: list Optional Objects to hide from hits. Each object must contain an `objectID` field. { "objectID": objectID }
`userData`	type: object Optional Custom JSON object that will be appended to the `userData` array in the response. This object is not interpreted by the API. It is limited to 1kB of minified JSON.

Rule ➔ rule ➔ consequence ➔ params


            query

type: string or query

Optional

When providing a string, it replaces the entire query string. When providing an object, it describes incremental edits to be made to the query string (but you can’t do both).

{
  "edits": list of edit
}


            automaticFacetFilters

type: list of automaticFacetFilter

Optional

Names of facets to which automatic filtering must be applied; they must match the facet name of a facet value placeholder in the query pattern. Ex. facetName1, facetName2. You can specify a score: facetName1\<score=5\>, facetName2\<score=1\>.


            automaticOptionalFacetFilters

type: object

Optional

Same syntax as automaticFacetFilters, but the engine treats the filters as optional. Behaves like optionalFilters.

Rule ➔ rule ➔ consequence ➔ promote-params

`objectID`	type: string Required Unique identifier of the object to promote.
`position`	type: integer Required Promoted rank for the object (zero-based).

Rule ➔ rule ➔ consequence ➔ hide


            objectID

type: string

Required

Unique identifier of the object to hide.

Rule ➔ rule ➔ validity ➔ timeRange

`from`	type: integer Required Lower bound of the time range (Unix timestamp).
`until`	type: integer Required Upper bound of the time range (Unix timestamp).

Rule ➔ rule ➔ consequence ➔ params ➔ automaticFacetFilter

`facet`	type: string Required Attribute to filter on. This must match a facet placeholder in the Rule’s pattern.
`score`	type: integer default: 1 Optional Score for the filter. Typically used for optional or disjunctive filters.
`disjunctive`	type: boolean default: false Optional Whether the filter is disjunctive (true) or conjunctive (false). If the filter applies multiple times, e.g. because the query string contains multiple values of the same facet, the multiple occurrences are combined with an `AND` operator by default (conjunctive mode). If the filter is specified as disjunctive, however, multiple occurrences are combined with an `OR` operator instead.

Rule ➔ rule ➔ consequence ➔ params ➔ query ➔ edits ➔ edit


            type

type: string

Required

Type of edit. Must be one of:

remove: when you want to delete some text and not replace it with anything
replace: when you want to delete some text and replace it with something else


            delete

type: string

Required

Text or patterns to remove from the query string.

[
  {
    "type": "remove",
    "delete": "red"
  }
]


            insert

type: string

Optional

Text that should be inserted in place of the removed text inside the query string.

[
  {
    "type": "replace",
    "delete": "red",
    "insert": "blue"
  }
]

Response

In this section we document the JSON response returned by the API. Each language will encapsulate this response inside objects specific to the language and/or the implementation. So the actual type in your language might differ from what is documented.

JSON format

Copy

        {
  "updatedAt":"2013-01-18T15:33:13.556Z",
  "taskID": 678
}

      

`updatedAt`	string Date at which the indexing job has been created.
`taskID`	integer The taskID used with the waitTask method.

Did you find this page helpful?

Save Rule | JavaScript API Client V3 (Deprecated)

About this method

Examples

Save a Rule

Save a Rule with alternatives enabled

Save a Rule with a context based condition

Parameters

Rule ➔ rule

Rule ➔ rule ➔ condition

Rule ➔ rule ➔ consequence

Rule ➔ rule ➔ consequence ➔ params

Rule ➔ rule ➔ consequence ➔ promote-params

Rule ➔ rule ➔ consequence ➔ hide

Rule ➔ rule ➔ validity ➔ timeRange

Rule ➔ rule ➔ consequence ➔ params ➔ automaticFacetFilter

Rule ➔ rule ➔ consequence ➔ params ➔ query ➔ edits ➔ edit

Response

JSON format

On this page